TikTok Shop Webhooks: Setup, Signing, and Retries

Every other TikTok Shop integration guide ends with the same unresolved question: how do you find out that something changed without asking every thirty seconds? Polling is the honest starting point, and it stops being honest somewhere around the point where your order volume makes a full sync expensive and a stale sync embarrassing. Webhooks are the answer the platform gives you — and they are also the surface where the most integration time disappears, because almost none of that time is spent on the webhook itself. It goes on authorization scope, request signing, and the difference between a callback you configured and a callback the platform will actually use.

What webhooks change, and what they do not

A webhook is a callback: you register an HTTPS endpoint, the platform posts an event to it when something happens, and your system reacts. Compared with the polling loop described in the Orders API guide, the win is latency and cost — you stop paying for calls that return "nothing changed", and you learn about a paid order in seconds rather than at the top of the next minute.

What webhooks do not change is your obligation to be correct. A delivery can be missed, delayed, duplicated, or arrive out of order. Treating the event stream as the sole source of truth is the single most common design mistake in commerce integrations, and it fails quietly: your order count is right for weeks and then one dropped delivery leaves a package unshipped with no error anywhere in your logs. The durable pattern is event-driven speed plus a scheduled reconciliation sweep that re-reads the authoritative list and repairs drift. Webhooks make you fast; reconciliation makes you right.

The webhook management surface

Webhook configuration lives on a small, three-verb surface at /event/202309/webhooks:

• GET — read the callbacks currently configured for a shop.
• PUT — set or replace the callback for one event type.
• DELETE — remove a shop-level callback.

That is the whole surface. There is no bulk-register call and no "subscribe to everything" switch: you address one event type at a time, which is deliberate — it means a partial rollout is expressible, and it means a mistake is scoped to a single event type rather than to your entire integration.

The version segment (202309) is part of the path, exactly as it is across the rest of the API. Pin it explicitly in your client rather than templating it from a config value you might bump globally; webhook management is the last surface you want silently migrated by a version bump intended for the catalog.

Scope first: whose webhooks are these?

Before writing any signing code, answer this question, because it invalidates everything downstream if you get it wrong: webhook configuration belongs to the app the shop authorized.

TikTok Shop credentials are not interchangeable. A credential set issued for one purpose — say, a warehouse or logistics integration — may be perfectly valid, sign correctly, and still be unable to manage webhooks, because the shops you care about authorized a different app. The diagnostic is cheap and worth building into your setup script: call the authorization endpoint that lists shops for the current credentials. If it returns success with an empty shop list, stop. Your credentials are working exactly as designed; they simply have no authority over the shop whose events you want.

This costs teams real days, because every symptom points the wrong way. The requests are well-formed, the signature is right, the token is valid, and the error message talks about app keys and shop ids — so the natural response is to re-examine the signing code, which is not the problem. Confirm scope before you debug cryptography.

The signing trap that costs the most time

The authentication and request signing guide covers the general algorithm. The webhook surface adds one wrinkle that breaks a surprising number of otherwise-correct clients: shop_cipher is a signed query parameter.

Most hand-rolled helpers sign a fixed parameter set — typically app_key and timestamp — and then append anything else to the URL string. That works everywhere the extra parameters are not signed. Here it does not. If shop_cipher rides along in the path or query without being included in the signature base, the signature you compute is not the signature the platform expects, and the request is rejected.

The signature base is the app secret, then the request path, then every signed parameter as key-and-value concatenated in sorted key order, then the app secret again — HMAC-SHA256, hex digest. For a webhook management call the signed set is app_key, shop_cipher, and timestamp. Send the request with those three plus sign as query parameters, and the access token in the x-tts-access-token header.

The reason this is worth calling out rather than leaving to the general guide is the error you get. An unsigned shop_cipher does not produce "bad signature". It produces a complaint about an invalid app key — which sends you to check a credential that is perfectly fine.

Reading error codes as they are meant, not as they read

Three responses on this surface mean something different from their English text. Building them into your client's error mapping saves the next engineer a day each:

• An "invalid app key" error most often means your signature base was wrong — usually a signed parameter you appended instead of signing. Check the signature base before you check the key.
• A shop-id error advising you to "ensure the shop is properly authorized" generally means the shop is not authorized to this app. Right signature, wrong app. This is the scope problem above, surfacing as a data error.
• An internal-error code on token refresh is very rarely an outage. It is almost always a stale or already-rotated refresh token. Refresh tokens rotate when used, so any environment file, snapshot, or fixture holding a copy goes stale the moment another process refreshes — and the platform reports that as a server-side failure rather than an authentication one.

That last one deserves a design note. Because refresh tokens rotate on use, two processes sharing one credential file will fight: whichever refreshes second presents a token the platform has already retired. Give every process a single owner for refresh, or a shared store that serializes it. Copying a working token into a second service is a bug with a delay fuse on it.

App defaults and per-shop overrides

The mental model most teams start with — "I register a webhook, therefore I receive events" — is one level too flat. There are two layers:

• An app-level default callback, configured once in Partner Center, that applies to every shop that authorized the app.
• A shop-level override, created with PUT, that applies to exactly one shop and one event type.

The practical consequences are worth internalizing. A GET that returns no shop-level configuration does not mean the shop receives nothing — it usually means deliveries follow the app-level default, which is the normal, healthy state. And DELETE does not turn events off for that shop; it removes the override and restores the default. If you want a shop to stop receiving an event entirely, that is a Partner Center change, not a DELETE.

The one-callback-per-event-type-per-shop rule also means PUT is a replace, not an add. There is no fan-out at this layer: if two internal consumers need the same event, receive it once at a single endpoint and fan out on your side, where you control retries and ordering.

Overrides are the right tool for staged rollouts — point one pilot shop at a new receiver, watch it for a week, then move the app default — but they are also easy to forget. Record the prior state before you write one, and give yourself a one-command rollback. An override nobody remembers creating is indistinguishable from a bug.

Verifying the push before you trust it

Your receiver is a public HTTPS endpoint, which means anyone can post to it. Verification is not optional hardening; it is the boundary that decides whether "order paid" is a fact or a claim.

Pushes carry a signature header containing a timestamp and a hex MAC. Verification is HMAC-SHA256 over the raw request body joined to the timestamp, keyed with your app secret, compared to the supplied MAC as lowercase hex. Two implementation details cause almost all the failures:

• Sign the raw bytes, not the re-serialized object. If your framework parses JSON before your handler sees it and you verify against JSON.stringify(parsedBody), key order and whitespace will differ from what was sent and every verification fails. Capture the raw body first — most frameworks need an explicit option for this.
• Enforce the replay window. The timestamp exists so a captured, valid request cannot be replayed forever. Reject anything outside roughly a five-minute window, and compare MACs with a constant-time function rather than string equality.

Verify before parsing, and return quickly. Do the work asynchronously: acknowledge the delivery, then process from a queue. A receiver that does its database writes inline is a receiver that times out on your busiest day, which is precisely when the retries pile up.

The envelope, and why idempotency is the whole game

Deliveries arrive with a small, predictable envelope around a per-event payload: an integer event type, the shop id, a timestamp, a unique notification id, and a data object whose shape depends on the type. Two design decisions follow from that shape.

First, event types are numeric. Map them to named constants in one place at the edge of your system and never let a bare integer travel further in. A magic number in a business rule is unreadable at 2am, and the mapping is exactly the kind of thing that changes as the platform adds events.

Second, and more consequentially, that notification id is your idempotency key. Retries are ordinary — a slow response, a network blip, or a deploy mid-delivery all produce one — so a handler that is not idempotent will eventually double-write. Record the id before processing, ignore anything you have already seen, and expire the record on a window comfortably longer than the platform's retry schedule. This is a dozen lines of code that prevents an entire category of duplicate orders, duplicate refunds, and duplicate notifications to customers.

Ordering deserves the same skepticism. Nothing guarantees that "shipped" cannot land before "paid". Where your state machine allows only forward transitions, use the event's own timestamp to reject stale updates rather than assuming arrival order reflects reality. The same discipline that keeps package state sane under retry keeps it sane under reordering.

What to build, in what order

Webhook work rewards a boring sequence, because each step makes the next one debuggable:

• Confirm scope. List the shops your credentials can see. If the list is empty, everything after this is wasted effort.
• Read before you write. Get the current configuration for one shop and one event type. A successful GET proves signing, token, and scope all at once — and it cannot break anything.
• Stand up a receiver that only verifies and logs. No business logic. Confirm real deliveries verify against the signature before you let a single one change your database.
• Add idempotency and a queue. Acknowledge fast, process asynchronously, deduplicate on the notification id.
• Override one shop. Point a pilot shop at the receiver with PUT, record the prior state, and keep the rollback command in your notes.
• Keep the reconciliation poll. Slow it down; never remove it. It is what catches the deliveries you never got, and it is how you find out that you are missing them.

Done in that order, the first four steps are entirely read-only or self-contained, so you can build most of a webhook integration without a single change that affects a live shop. That is the same principle behind sequencing settlement reads before any write path: prove the plumbing with calls that cannot hurt you, then turn on the ones that can.

If you are weighing whether to build this in-house at all, the honest test is whether event-driven sync is on your critical path today or a quarter from now. A shop doing double-digit orders a day is well served by polling and a good reconciliation job. The economics change with volume, and so does the cost of getting idempotency wrong. TikTok Shop management teams that already run this plumbing across multiple shops absorb the platform's sharp edges as a fixed cost rather than rediscovering each one — and if you are deciding between building and partnering, what a TikTok Shop agency actually does on the operations side is mostly this: the unglamorous reliability work between the events and the ledger.