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.

17 events covered

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

Signature header
authorization

Format: `<lowercase hex>`, with no `Bearer` prefix

Scheme
HMAC-SHA256, lowercase hex
Signed material
{app_key}{raw body}

Your app key, then the raw request body as sent, with nothing between them.

How events are identified
type field in the body, a number rather than the event name
Body format
JSON

Content type: application/json.

Envelope
type, tts_notification_id, shop_id, timestamp, data
Agent skill
npx skills add hookdeck/webhook-skills --skill tiktok-shop-webhooks

Verify TikTok Shop webhooks →

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 an address and an event_type and needs the seller.authorization.info scope. GET and DELETE on 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 abcdef and app secret 123.
  • We found no documented way to resend a delivery. Recover missed events by fetching the data from the Partner API.

Delivery behaviour

  1. 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 →
  2. 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 →
  3. Duplicate deliveries

    Delivery is at-least-once, so the same event can arrive more than once during retries. Deduplicate on tts_notification_id when the body has one, and keep your handlers idempotent.

    Handle duplicates →
  4. Misreading the numeric `type`

    The body's type is a number, and TikTok publishes no complete mapping from numbers to event_type strings. Give each topic its own URL and check the fields in data, rather than relying on the number alone.

    Identify the topic →

TikTok Shop webhook best practices

  • Verify every delivery. The signature is in Authorization, with no Bearer prefix, 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_type arrived, and check the fields you expect in data.
  • 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_EXPIRATION starts 30 days before a seller's authorization expires, and SELLER_DEAUTHORIZATION tells 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

PRODUCT_STATUS_CHANGE · PRODUCT_INFORMATION_CHANGE · PRODUCT_CREATION · PRODUCT_CATEGORY_CHANGE +1

5 5
order

ORDER_STATUS_CHANGE · CANCELLATION_STATUS_CHANGE · RETURN_STATUS_CHANGE · REVERSE_STATUS_UPDATE

4 3
fulfillment

RECIPIENT_ADDRESS_UPDATE · PACKAGE_UPDATE · INVOICE_STATUS_CHANGE

3 3
messages

NEW_CONVERSATION · NEW_MESSAGE · NEW_MESSAGE_LISTENER

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.

Not affiliated with TikTok Shop. Facts are compiled from public sources and linked inline.