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

Published · Updated

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 overview, every topic is on TikTok Shop webhook events, and signature verification code is on Verify TikTok Shop webhooks.

At a glance

ProblemWhat to doWith Event Gateway
TimeoutsReturn HTTP 200 within 3 seconds; process in a background jobAccepts the delivery at once, then queues it for your service
DuplicatesRecord each tts_notification_id, and make processing idempotentDrops repeats before they reach your handler
OrderingCompare update_time or fetch current state; don't rely on arrival orderLogs every event and attempt, so you can see arrival order when debugging
RetriesPlan for TikTok Shop stopping after the fourth retry; reconcile from the Partner APIAccepts deliveries while your service is down and replays them
Identifying topicsGive each topic its own URL; don't rely on the numeric type aloneFilters and routes on any field in the body
TestingReceive real deliveries locally and test verification against TikTok's worked exampleForwards to localhost and replays past events
Other limitsHandle authorization expiry; check which topics your market and scopes allowLogs every delivery, so you can see when an authorization event arrived

TikTok Shop webhook timeouts and slow handlers

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

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: the same result however many times it runs.

With Event Gateway: Hookdeck deduplicates 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

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.

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

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 automatically, manually or in bulk once you recover.

Identifying and choosing TikTok Shop topics

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.

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 and routes events on any body field, including type, so one source can feed several services.

Testing and debugging TikTok Shop webhooks locally

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 has sample payloads to start from.

With Event Gateway: The Hookdeck CLI receives webhooks on your machine without a public server, and you can replay past events with one click.

Other TikTok Shop webhook 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.

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.