TikTok Shop webhooks
TikTok Shop webhooks are HTTP POST requests TikTok Shop sends to the callback URL your app registered when a topic a shop subscribes to, such as ORDER_STATUS_CHANGE, fires.
How TikTok Shop webhooks work
Webhooks tell your app about orders, packages, products and conversations as they change, so you don't have to keep polling the Partner API. A shop subscribes to a topic by its event_type string, with a webhook URL for that topic. These pages list those strings. TikTok also numbers other topics, such as size chart and Fulfilled by TikTok changes, that have no event_type string.
TikTok's example bodies for these topics have a numeric type, a shop_id, a timestamp and a data object whose fields depend on the topic, and all but one have a tts_notification_id. The body doesn't carry the event_type string. Each topic's page gives it a number, such as 1 for ORDER_STATUS_CHANGE, but TikTok says it publishes no complete mapping and advises against branching on the number alone.
Key facts
authorization Format: `<lowercase hex>`, with no `Bearer` prefix
{app_key}{raw body} Your app key, then the raw request body as sent, with nothing between them.
type field in the body, a number rather than the event name Setting up TikTok Shop webhooks
- Add your webhook URL and choose topics in Partner Center, under App & Service, your app, Basic Information, Developing. To set the URL for one topic on one shop, call
PUT /event/202309/webhooks, which takes anaddressand anevent_typeand needs theseller.authorization.infoscope.GETandDELETEon the same path list and remove them. - To receive webhooks on your machine, use the Hookdeck CLI:
hookdeck listen 3000 tiktok-shop. - To test verification without a delivery, use the worked example in TikTok's webhooks overview, which publishes a body and its signature for app key
abcdefand app secret123. - We found no documented way to resend a delivery. Recover missed events by fetching the data from the Partner API.
Delivery behaviour
3 seconds return HTTP 200 within this window Retries 4 2 minutes, 30 minutes, 3 hours and 12 hours, each after the last failure After retries run out TikTok Shop stops reconcile from the Partner API to recover the event Duplicates at-least-once deduplicate on tts_notification_id when the body has one Known failure modes
From Hookdeck's TikTok Shop guide →-
A slow handler starts the retries
TikTok Shop expects HTTP 200 within 3 seconds. Respond first and do the work in a background job, because a failed push is retried and can reach you more than once.
Timeouts and slow handlers → -
Events are lost after the fourth retry
TikTok Shop retries a failed push 4 times over about 15 and a half hours, then stops. Reconcile from the Partner API to find what you missed.
Recover missed events → -
Duplicate deliveries
Delivery is at-least-once, so the same event can arrive more than once during retries. Deduplicate on
Handle duplicates →tts_notification_idwhen the body has one, and keep your handlers idempotent. -
Misreading the numeric `type`
The body's
Identify the topic →typeis a number, and TikTok publishes no complete mapping from numbers toevent_typestrings. Give each topic its own URL and check the fields indata, rather than relying on the number alone.
TikTok Shop webhook best practices
- Verify every delivery.
The signature is in
Authorization, with noBearerprefix, and covers your app key plus the raw body. Check it before you parse the JSON. - Return 200 within three seconds. Verify, put the event on a queue and respond. Do database writes and API calls in a worker.
- Deduplicate on `tts_notification_id`. Delivery is at-least-once. TikTok says to store this ID when the body has one, so have a fallback key for a body without it.
- Don't rely on the number in `type` alone.
Use the Events API to give each topic its own webhook URL, so the route tells you which
event_typearrived, and check the fields you expect indata. - Reconcile with the Partner API. TikTok Shop stops after the fourth retry. A scheduled job that fetches recent orders and products catches whatever was lost.
- Handle authorization topics.
UPCOMING_AUTHORIZATION_EXPIRATIONstarts 30 days before a seller's authorization expires, andSELLER_DEAUTHORIZATIONtells you it has gone. Subscribe to both if you need long-lived shop access.
Common TikTok Shop webhook events
Orders
ORDER_STATUS_CHANGE | Order is placed or its status changes |
CANCELLATION_STATUS_CHANGE | Order's cancellation request changes status |
RETURN_STATUS_CHANGE | Order's return, refund or replacement request changes status |
Packages and products
PACKAGE_UPDATE | Package is combined, split or otherwise changed |
PRODUCT_STATUS_CHANGE | Product passes or fails audit, or the platform changes its status |
Authorization
SELLER_DEAUTHORIZATION | Seller has been deauthorized from your app |
UPCOMING_AUTHORIZATION_EXPIRATION | Authorization expires in 30 days; repeats daily until re-authorized |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
product | 5 | 5 |
order | 4 | 3 |
fulfillment | 3 | 3 |
messages | 3 | 3 |
1 more resource, including Other TikTok Shop events. All 17 events →
In this hub
| Webhook events → | Every covered TikTok Shop event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to TikTok Shop events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill tiktok-shop-webhooks |
Keep a slow handler from using up TikTok Shop's retries.
Hookdeck Event Gateway accepts each TikTok Shop delivery straight away, verifies the signature, queues events and retries to your service on your schedule, so a failure on your side doesn't lose the event once TikTok Shop's retries run out.