Configuration guide

Webhooks notify your HTTPS endpoint when subscribed TikTok Shop events occur. You can configure webhook subscriptions in Partner Center Console or with the Events API.

There are two supported configuration methods:

Use one operational source of truth for each app or shop. Partner Center and the Events API manage the same webhook configuration surface; changes made in one place can affect what you see in the other.

Before you configure webhooks, make sure that:

• You understand the webhook event model and payload format. See Webhooks overview.
• Your app has the API scopes and topic permissions required by the events you want to subscribe to.
• Your receiving service exposes a reachable HTTPS endpoint that meets the webhook URL requirements below.
• If you use the Events API, you can send signed TikTok Shop API requests and provide a valid x-tts-access-token when the endpoint requires it. See Sign your API request.

Use this path for webhook URL and topic configuration:

Partner Center Console
  -> App & Service
  -> Select your app or service
  -> Basic Information
  -> Developing
  -> Webhook URL / Event subscriptions

Use Development Kits > Webhook Log only when you want to inspect delivery history. It is a monitoring entry, not the webhook configuration entry.

Add your HTTPS webhook receiver URL in the Developing section under Basic Information. Image creenshot reference: the webhook URL field is in the app or service configuration area, not in Development Kits.

Image

Partner Center may preselect default webhook notifications for your app. The exact default set can vary by app type, market, seller type, and approved scopes, so confirm the selected default topics in the Partner Center subscription UI before launch. For optional topics, select only the events your integration actually handles. Common webhook categories include:

For the full and current event list, use the event list in Webhooks overview and the event-specific reference pages linked from that overview. Image creenshot reference: use this area to confirm which topics are selected by default and which optional topics you have enabled.

Image

TikTok Shop sends an HTTP POST request to your configured URL when a subscribed event occurs. The request body contains JSON data for the event. TikTok Shop verifies SSL certificates when delivering payloads to HTTPS webhook addresses. Make sure your server certificate is valid and trusted. TikTok Shop places the webhook signature in the Authorization request header. This webhook signature is different from the signature you generate when your app calls TikTok Shop APIs. For webhook verification:

1. Read the raw request body exactly as received.
2. Concatenate {app_key}{raw_webhook_payload} with no added whitespace or reformatting.
3. Use your app secret as the HMAC-SHA256 key.
4. Compare the generated lowercase hexadecimal value with the Authorization header value.

Do not parse and re-serialize the JSON body before verification. Reformatting the body can change whitespace or field order and cause signature verification to fail. For the webhook signing example, see the Webhooks Header and Body section in Webhooks overview.

Return a response within 3 seconds for each notification.

TikTok Shop stops retrying after the 4th retry failure.

Webhook delivery is at-least-once. Your listener must be idempotent because the same event can be delivered more than once during retries. Store and deduplicate by tts_notification_id when it is present in the payload. If an event-specific payload does not include tts_notification_id, use the most stable available combination, such as event type, shop_id, timestamp, and the business object ID.

Use the Events API when you need to create, inspect, or delete webhook subscriptions programmatically. Before calling these APIs:

Events API configuration and Partner Center configuration are not mutually exclusive. They update the same underlying subscription configuration. If you call Update Shop Webhook for a shop and event that was configured manually, the API can update or replace that shop-event configuration. After any API change, call Get Shop Webhooks or check Partner Center to confirm the final state. Available Events API operations:

Use this path to inspect webhook delivery logs:

Partner Center Console
  -> Development Kits
  -> Webhook Log
  -> Select the app or service

The webhook log is for monitoring and debugging delivery history. Use it to confirm whether TikTok Shop sent a notification, which callback URL was used, and what response your server returned. Screenshot reference: this screenshot shows the log and debugging entry under Development Kits, separate from the app configuration entry under App & Service > Developing.

Image