# TikTok Shop webhooks in production: duplicates, ordering, retries and timeouts

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

This guide covers the problems TikTok Shop webhooks cause in production and how to handle each one. What TikTok Shop sends and how it's signed is on the [TikTok Shop webhooks](/webhooks/tiktok-shop) overview, every topic is on [TikTok Shop webhook events](/webhooks/tiktok-shop/events), and signature verification code is on [Verify TikTok Shop webhooks](/webhooks/tiktok-shop/verify).

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#timeouts) | Return HTTP 200 within 3 seconds; process in a background job | Accepts the delivery at once, then queues it for your service |
| [Duplicates](#duplicates) | Record each `tts_notification_id`, and make processing idempotent | Drops repeats before they reach your handler |
| [Ordering](#ordering) | Compare `update_time` or fetch current state; don't rely on arrival order | Logs every event and attempt, so you can see arrival order when debugging |
| [Retries](#retries) | Plan for TikTok Shop stopping after the fourth retry; reconcile from the Partner API | Accepts deliveries while your service is down and replays them |
| [Identifying topics](#choosing-events) | Give each topic its own URL; don't rely on the numeric `type` alone | Filters and routes on any field in the body |
| [Testing](#testing) | Receive real deliveries locally and test verification against TikTok's worked example | Forwards to localhost and replays past events |
| [Other limits](#other-limits) | Handle authorization expiry; check which topics your market and scopes allow | Logs every delivery, so you can see when an authorization event arrived |

## TikTok Shop webhook timeouts and slow handlers {#timeouts}

Return HTTP 200 within 3 seconds, then do the work in a background job.

**Why it happens:** TikTok Shop's docs ask for HTTP 200 within 3 seconds when you accept a notification. Handlers that write to a database or call the Partner API before responding can run out of time, and a failed push starts the retry schedule.

**Fix it in your handler:**

1. Verify the signature and return 200 straight away.
2. Push the event onto a queue and process it in a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
3. Do no blocking work, such as API calls or database writes, before you respond.

**With Event Gateway:** Hookdeck accepts each TikTok Shop delivery immediately, then queues events and delivers them to your service at a rate it can handle, with its own retries. Your handler can take longer without failing a TikTok Shop push.

## Duplicate TikTok Shop webhooks {#duplicates}

TikTok Shop's delivery is at-least-once, so the same event can arrive more than once. Deduplicate on `tts_notification_id` and make processing idempotent.

**Why it happens:** TikTok Shop retries a push it counts as failed, so a delivery your handler processed but didn't acknowledge in time can come back. Its docs say your listener must be idempotent.

**Fix it in your handler:**

1. Read `tts_notification_id` from the body. TikTok says to store it when it's present, so have a fallback for a body without it, such as a hash of the raw body.
2. Check a persistent store for that ID. If it's there, skip processing and return 200.
3. If it's new, process the delivery and save the ID.
4. Make every handler [idempotent](/webhooks/guides/implement-webhook-idempotency): the same result however many times it runs.

**With Event Gateway:** Hookdeck [deduplicates](/docs/deduplication) events before they reach your endpoint, and you can key that on `body.tts_notification_id`, so repeats are filtered at the infrastructure level rather than in each handler.

## Out-of-order TikTok Shop webhooks {#ordering}

TikTok Shop documents no ordering guarantee. Compare timestamps or fetch current state rather than relying on when a delivery arrives.

**Why it happens:** A retry can arrive hours after the first attempt, by which time newer events for the same order have already reached you. For more on the general problem, see [Webhook Ordering: Why It's Hard and How to Handle It](/webhooks/guides/webhook-ordering-why-its-hard-and-how-to-handle-it).

**Fix it in your handler:**

1. Keep the last `update_time` you processed for each resource, where the topic's `data` has one, and skip anything older.
2. When an event is ambiguous, fetch the order or product from the Partner API.
3. Write state transitions that tolerate events in any order.

**With Event Gateway:** Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.

## TikTok Shop webhook retries {#retries}

TikTok Shop retries a failed push 4 times over about 15 and a half hours, then stops. Reconcile from the Partner API to recover anything you missed.

**Why it happens:** The first retry comes 2 minutes after the initial failure, the second 30 minutes after that, the third 3 hours after that and the fourth 12 hours after that. TikTok Shop stops once the fourth retry fails, so a long outage loses the event.

**Fix it in your handler:**

1. Alert on failed requests to your webhook endpoint, so you find out before the retries run out.
2. Run a scheduled job that fetches recent orders and products from the Partner API and repairs anything stale.
3. Run that job by hand after any outage. We found no documented way to ask TikTok Shop to resend a delivery.

**With Event Gateway:** Hookdeck captures every TikTok Shop delivery while your services are down, so TikTok Shop's pushes succeed and its retries aren't used up. Failed events can be [retried](/docs/retries) automatically, manually or in bulk once you recover.

## Identifying and choosing TikTok Shop topics {#choosing-events}

Give each topic its own webhook URL, and subscribe only to what you process. The numeric `type` in the body isn't enough on its own.

**Why it matters:** You subscribe with an `event_type` string, but the body carries a number in `type` and no `event_type`. Each topic's page gives it a number, such as `1` for `ORDER_STATUS_CHANGE`, but TikTok says it publishes no complete mapping and tells you not to branch on the number alone. Use the subscribed `event_type` and the topic's payload schema instead. Every topic is on [TikTok Shop webhook events](/webhooks/tiktok-shop/events).

**Fix it in your handler:**

1. Register a separate URL for each `event_type` with `PUT /event/202309/webhooks`, such as `/webhooks/tiktok-shop/order-status`, so the route tells you which topic arrived.
2. Check the fields you expect in `data` before you act on them.
3. Log any `type` you don't recognize instead of rejecting it.

**With Event Gateway:** Hookdeck [filters](/docs/filters) and routes events on any body field, including `type`, so one source can feed several services.

## Testing and debugging TikTok Shop webhooks locally {#testing}

Receive real deliveries on your machine with a CLI, and test verification against TikTok's worked example.

**Why it matters:** TikTok Shop needs a public URL to send to, and development machines sit behind NAT and firewalls. Producing a specific order status also takes real activity on a shop.

**Fix it in your handler:**

1. Use a tunnel with a public URL, and register it as the webhook URL for the topic you're working on.
2. Test your verification against the worked example in TikTok's webhooks overview, which publishes a body and its signature for app key `abcdef` and app secret `123`.
3. Keep fixtures of real payloads for edge cases; [TikTok Shop webhook events](/webhooks/tiktok-shop/events) has sample payloads to start from.

**With Event Gateway:** The [Hookdeck CLI](/docs/cli) receives webhooks on your machine without a public server, and you can replay past events with one click.

## Other TikTok Shop webhook limits {#other-limits}

Plan for authorization expiry and for topics limited by market or scope before they reach production.

**Authorization expiry.** `UPCOMING_AUTHORIZATION_EXPIRATION` fires 30 days before a seller's authorization expires, then once a day at 0:00 until the seller authorizes again. `SELLER_DEAUTHORIZATION` fires after a seller is deauthorized. Subscribe to both if you need long-lived shop access, and stop calling the Partner API for that shop when authorization has gone.

**Topics limited by market or scope.** `INVOICE_STATUS_CHANGE` follows the Upload Invoice endpoint, which applies only to the Brazil market. Some product topics need the Product Basic API scope. Check your app's configuration in Partner Center for the topics you're entitled to.

**Topics with no `event_type`.** TikTok numbers more webhook topics than the `event_type` strings it lists, including Fulfilled by TikTok, affiliate creator, promotion and size chart topics. Check how to enable these in Partner Center before you design around one.

**With Event Gateway:** Hookdeck keeps a log of every delivery, so you can look up when an authorization event arrived, and sends one TikTok Shop source's events to as many destinations as you need.