Skip to main content

Receive Webhook (TikTok → SKU.io)

POST 
/webhooks/tiktok-shop

Global (per-environment) endpoint that receives signed webhook events from TikTok Shop — this is the URL configured on the TikTok Shop app.

No bearer auth: the request is authenticated by TikTok's HMAC signature in the Authorization header (HMAC-SHA256 over app_secret + raw_body, keyed by the app secret — sandbox or production secret chosen by the resolved instance's environment setting).

Tenant routing: every tenant's webhooks arrive at this ONE URL. The InitializeTenantFromWebhookPayload middleware resolves the tenant from the payload shop_id (top-level or data.shop_id) via the central tenant_integration_routes registry (external_key = the instance's primary shop id), forwards to the tenant's home pod if needed, initialises tenancy, and exposes the instance to the controller.

Flow: 400 empty body → 404 missing/unknown shop_id → 401 invalid signature → 422 missing type → 200 event persisted + processing job dispatched.

Topics by type: 1 ORDER_STATUS_CHANGE, 2 REVERSE_STATUS_CHANGE, 5 PACKAGE_UPDATE, 7 PRODUCT_STATUS_CHANGE, 12 AUTHORIZATION_CANCELLATION; unknown types stored as TYPE_{n}.

Request​

Responses​

OK

Response Headers
    Content-Type