# 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.

Agent skill: `npx skills add hookdeck/webhook-skills --skill tiktok-shop-webhooks` ([details](https://hookdeck.com/webhooks/tiktok-shop/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [TikTok Shop's official docs](https://partner.tiktokshop.com/docv2/page/tts-webhooks-overview).

[Overview](https://hookdeck.com/webhooks/tiktok-shop) · [Webhook events (17)](https://hookdeck.com/webhooks/tiktok-shop/events) · [MCP events](https://hookdeck.com/webhooks/tiktok-shop/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/tiktok-shop/verify) · [Production guide](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/tiktok-shop/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `authorization` Format: `<lowercase hex>`, with no `Bearer` prefix | [TikTok Shop docs](https://partner.tiktokshop.com/docv2/page/tts-webhooks-overview) |
| Scheme | `HMAC-SHA256, lowercase hex` | [TikTok Shop docs](https://partner.tiktokshop.com/docv2/page/tts-webhooks-overview) |
| Signed material | `{app_key}{raw body}` Your app key, then the raw request body as sent, with nothing between them. | [TikTok Shop docs](https://partner.tiktokshop.com/docv2/page/tts-webhooks-overview) |
| How events are identified | `type field in the body, a number rather than the event name` | [TikTok Shop docs](https://partner.tiktokshop.com/docv2/page/tts-webhooks-overview) |
| Body format | `JSON` Content type: application/json. | [TikTok Shop docs](https://partner.tiktokshop.com/docv2/page/tts-webhooks-overview) |
| Envelope | `type, tts_notification_id, shop_id, timestamp, data` | [TikTok Shop docs](https://partner.tiktokshop.com/docv2/page/tts-webhooks-overview) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill tiktok-shop-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/tiktok-shop/skill) |

[Verify TikTok Shop webhooks](https://hookdeck.com/webhooks/tiktok-shop/verify)

## 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.

## 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](/docs/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

- **Timeout:** 3 seconds. return HTTP 200 within this window. [Guide](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#timeouts)
- **Retries:** 4. 2 minutes, 30 minutes, 3 hours and 12 hours, each after the last failure. [Guide](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#retries)
- **After retries run out:** TikTok Shop stops. reconcile from the Partner API to recover the event. [Guide](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#retries)
- **Duplicates:** at-least-once. deduplicate on `tts_notification_id` when the body has one. [Guide](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#duplicates)

## Known failure modes

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](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#timeouts)
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](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#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](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#choosing-events)

From [Hookdeck's TikTok Shop guide](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts).

## TikTok Shop webhook best practices

- **[Verify every delivery](https://hookdeck.com/webhooks/tiktok-shop/verify).** 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](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#timeouts).** Verify, put the event on a queue and respond. Do database writes and API calls in a worker.
- **[Deduplicate on `tts_notification_id`](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#duplicates).** 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](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#choosing-events).** 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](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#retries).** TikTok Shop stops after the fourth retry. A scheduled job that fetches recent orders and products catches whatever was lost.
- **[Handle authorization topics](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts#other-limits).** `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](https://hookdeck.com/webhooks/tiktok-shop/events#ORDER_STATUS_CHANGE): Order is placed or its status changes
- [CANCELLATION_STATUS_CHANGE](https://hookdeck.com/webhooks/tiktok-shop/events#CANCELLATION_STATUS_CHANGE): Order's cancellation request changes status
- [RETURN_STATUS_CHANGE](https://hookdeck.com/webhooks/tiktok-shop/events#RETURN_STATUS_CHANGE): Order's return, refund or replacement request changes status

### Packages and products

- [PACKAGE_UPDATE](https://hookdeck.com/webhooks/tiktok-shop/events#PACKAGE_UPDATE): Package is combined, split or otherwise changed
- [PRODUCT_STATUS_CHANGE](https://hookdeck.com/webhooks/tiktok-shop/events#PRODUCT_STATUS_CHANGE): Product passes or fails audit, or the platform changes its status

### Authorization

- [SELLER_DEAUTHORIZATION](https://hookdeck.com/webhooks/tiktok-shop/events#SELLER_DEAUTHORIZATION): Seller has been deauthorized from your app
- [UPCOMING_AUTHORIZATION_EXPIRATION](https://hookdeck.com/webhooks/tiktok-shop/events#UPCOMING_AUTHORIZATION_EXPIRATION): Authorization expires in 30 days; repeats daily until re-authorized

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [product](https://hookdeck.com/webhooks/tiktok-shop/events#resource-product) | 5 | 5 |
| [order](https://hookdeck.com/webhooks/tiktok-shop/events#resource-order) | 4 | 3 |
| [fulfillment](https://hookdeck.com/webhooks/tiktok-shop/events#resource-fulfillment) | 3 | 3 |
| [messages](https://hookdeck.com/webhooks/tiktok-shop/events#resource-messages) | 3 | 3 |

1 more resource. [All 17 events](https://hookdeck.com/webhooks/tiktok-shop/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/tiktok-shop/events): Every covered TikTok Shop event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/tiktok-shop/mcp-events): How an agent subscribes to TikTok Shop events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/tiktok-shop/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/tiktok-shop/guide-duplicates-ordering-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/tiktok-shop/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill tiktok-shop-webhooks`
---

Not affiliated with TikTok Shop. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/tiktok-shop.json) · [Report a correction](https://hookdeck.com/contact)
