Overview

Webhooks enable real-time HTTPS notifications for TikTok Shop events. After a shop subscribes to a webhook topic, TikTok Shop sends an HTTP POST request to the callback URL registered by the app when the subscribed event occurs. Do not rely on webhooks as the only source of truth. Network failures, endpoint downtime, retries, or delayed delivery can happen, so your system should also reconcile critical business state through scheduled API polling.

The diagram below shows the order-status webhook flow. The same delivery pattern applies to other webhook topics. Image

1. The app subscribes to a webhook topic, such as ORDER_STATUS_CHANGE, for a shop.
2. The app registers an HTTPS endpoint hosted by the app server.
3. A matching business event happens in the shop, such as a new order or an order-status update.
4. TikTok Shop publishes the event to the subscribed webhook topic.
5. TikTok Shop sends a webhook request with the topic-specific payload to the registered endpoint.

Use the event_type value when configuring a shop webhook with the webhook API or in Partner Center. The delivered payload also contains a numeric type field. The shared Event API schema publishes the full event_type enum, but it does not publish a complete numeric type mapping for every topic. Do not branch only on the numeric type; use the subscribed event_type context and the topic-specific payload schema.

For shop connection lifecycle handling, subscribe to both UPCOMING_AUTHORIZATION_EXPIRATION and SELLER_DEAUTHORIZATION when your app needs to maintain long-lived shop access.

You can configure a shop webhook in Partner Center or through the Event API. In Partner Center, open the app or service and go to the webhook or event-subscription settings:

Partner Center
  -> App & Service
  -> Select the app or service
  -> Webhooks / Event subscriptions
  -> Add or update the topic and callback URL

Console labels may vary by Partner Center version. The required configuration is the webhook topic, represented by event_type, and an HTTPS callback URL controlled by your app. To configure a webhook by API, call Update Shop Webhook:

PUT https://open-api.tiktokglobalshop.com/event/202309/webhooks?app_key={app_key}&timestamp={timestamp}&sign={sign}&shop_cipher={shop_cipher}
Content-Type: application/json
x-tts-access-token: {access_token}

{
  "address": "https://example.com/tiktok-shop/webhooks",
  "event_type": "ORDER_STATUS_CHANGE"
}

Use Get Shop Webhooks to inspect the currently configured webhook topics and callback URLs for a shop. Use Delete Shop Webhook only when you intentionally want to remove a topic subscription.

TikTok Shop sends the webhook signature in the HTTP Authorization header. The value is the lowercase hexadecimal HMAC-SHA256 digest. It is not a bearer token and should not include a Bearer prefix. The signature is calculated as follows:

signature_base_string = app_key + raw_request_body
signature = HMAC-SHA256(signature_base_string, app_secret)

Important validation rules:

Reproducible example:

1. App key:

abcdef

1. Raw request body:

{"type":1,"tts_notification_id":"7380066284010030890","shop_id":"7495540735365777507","timestamp":1718305585,"data":{"is_on_hold_order":true,"order_id":"576653688135258178","order_status":"UNPAID","update_time":1718305585}}

1. Signature base string:

abcdef{"type":1,"tts_notification_id":"7380066284010030890","shop_id":"7495540735365777507","timestamp":1718305585,"data":{"is_on_hold_order":true,"order_id":"576653688135258178","order_status":"UNPAID","update_time":1718305585}}

1. App secret:

123

1. HMAC-SHA256 result:

5dec0f11ec2f6783b8deee53c9ffbf8d024302f7c7e7fa55a35d17629031ac05

Pseudocode:

const crypto = require("crypto");

function verifyWebhookSignature({ appKey, appSecret, rawBody, authorization }) {
  const base = appKey + rawBody;
  const expected = crypto
    .createHmac("sha256", appSecret)
    .update(base, "utf8")
    .digest("hex");

  const expectedBuffer = Buffer.from(expected, "utf8");
  const receivedBuffer = Buffer.from(authorization || "", "utf8");

  return (
    expectedBuffer.length === receivedBuffer.length &&
    crypto.timingSafeEqual(expectedBuffer, receivedBuffer)
  );
}

All webhook notifications include common metadata and a topic-specific data object.

The sample request below uses the same raw body and signature shown in the reproducible example.

curl --location --request POST 'https://example.com/tiktok-shop/webhooks' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: 5dec0f11ec2f6783b8deee53c9ffbf8d024302f7c7e7fa55a35d17629031ac05' \
  --data-raw '{"type":1,"tts_notification_id":"7380066284010030890","shop_id":"7495540735365777507","timestamp":1718305585,"data":{"is_on_hold_order":true,"order_id":"576653688135258178","order_status":"UNPAID","update_time":1718305585}}'

• Get Shop Webhooks
• Update Shop Webhook
• Delete Shop Webhook
• Order Status Change webhook
• Seller deauthorization webhook
• Upcoming authorization expiration webhook
• Reauthorize shops
• Disconnecting shops