← All posts
Tutorial

TikTok Shop Customer Service API Webhook: Production Checklist

To put a TikTok Shop Customer Service API webhook into production, subscribe the authorized shop to NEW_MESSAGE, verify every notification before accepting it, return 200 within three seconds, and process the message asynchronously. Then reconcile the webhook with Get Conversation Messages, because TikTok explicitly warns that webhooks alone are not a complete source of truth. This path requires the approved Shop customer-service scope and seller authorization.

Key takeaways

  • TikTok Shop’s Customer Service API covers buyer-to-seller Shop conversations, not every DM sent to an ordinary TikTok account.
  • The New Message webhook is event type 14; its payload includes tts_notification_id, shop_id, message_id, conversation_id, index, create_time, message type, visibility, and sender data.
  • The receiver must use HTTPS with TLS 1.2 or later, verify the Authorization signature, and answer with 200 within three seconds.
  • Put work behind a queue and make it idempotent: retries occur after failed delivery, and webhook delivery can still be incomplete.
  • Reconcile gaps with GET /customer_service/202309/conversations/{conversation_id}/messages; fetching messages does not mark them read.

TikTok Shop Customer Service API webhook setup

This checklist starts after eligibility review. If the app has not yet received the custom Customer Service scope, use the approval and eligibility checklist first. TikTok currently documents seller.customer_service for conversation APIs, while the Update Shop Webhook operation uses seller.authorization.info. Confirm both the app’s enabled scopes and the seller token’s grants before treating a webhook failure as a networking problem.

The official Customer Service API exposes New Conversation and New Message hooks. For message intake, configure NEW_MESSAGE either in Partner Center or with:

PUT /event/202309/webhooks
event_type: NEW_MESSAGE
address: https://support.example.com/webhooks/tiktok-shop

The API form also requires the normal signed request parameters, seller access token, and shop_cipher. Do not copy this example address into production; use a stable endpoint owned by your service.

Production implementation checklist

1. Separate acknowledgement from processing

TikTok requires a successful 200 response with an empty body within three seconds. Verify the request, persist a minimal durable record, enqueue the work, and acknowledge. Do not call order systems, an AI model, or a CRM before responding.

On delivery failure, TikTok documents up to four retries: two minutes after the initial failure, then 30 minutes, three hours, and 12 hours after the preceding failure. Store tts_notification_id and message_id, and make repeated processing harmless. This is an implementation safeguard, not a promise that either field will replace your own event ledger.

2. Verify the TikTok Shop signature on the raw body

TikTok Shop places an HMAC-SHA256 signature in the Authorization header. Preserve the raw request bytes, calculate the expected value using the current app credentials exactly as described in the official webhook guide, and use a constant-time comparison. Return 401 when authentication fails; never log the app secret, seller access token, full signature, or buyer message body during diagnosis.

This signature format belongs to TikTok Shop. It is different from UnifyPort’s X-Device-Timestamp and X-Device-Signature headers, so do not reuse one verifier for both protocols.

3. Normalize only after preserving identifiers

Keep the original shop_id, conversation_id, message_id, index, create_time, sender role, type, and is_visible before mapping the event into your ticket model. A larger index means a newer message according to TikTok’s New Message reference. Do not assume arrival order matches message order.

Route invisible or unsupported message types to an explicit review state instead of silently converting them to text. The Customer Service API overview lists more message forms than a basic chat UI may render.

4. Reconcile the conversation history

After a webhook is accepted, fetch the conversation when an index gap appears, a worker restarts, or an operator requests replay. The official history endpoint is:

GET /customer_service/202309/conversations/{conversation_id}/messages

It requires seller.customer_service; page_size is at most 10, and subsequent pages use next_page_token. Sort by index when reconstructing message order. Calling this endpoint does not mark messages as read, so invoke the separate Read Message operation only when your product’s agent workflow has actually consumed the message.

5. Run a production acceptance test

Use an authorized development or production shop and record non-secret evidence for this sequence:

  1. A buyer starts or continues a Shop customer-service conversation.
  2. The endpoint receives type 14, validates the signature, and returns 200 within three seconds.
  3. One queue job creates or updates the correct conversation using shop_id plus conversation_id.
  4. A deliberate worker retry does not create a duplicate message.
  5. Get Conversation Messages returns the same message_id; an induced index gap is recovered.
  6. Partner Center’s Development Kits → Webhook Log shows the accepted delivery.

Where UnifyPort fits

Use TikTok Shop’s official Customer Service API when you need Shop buyer identity, seller authorization, order-linked support, native agent status, or official Shop replies. UnifyPort neither grants seller.customer_service nor turns ordinary TikTok DMs into Shop conversations.

For the separate ordinary-account inbound use case, UnifyPort can deliver supported TikTok messages as normalized message.received events. Review the general TikTok DM API boundary and the current provider message-support matrix before choosing that path. Its webhook receiver follows the independent UnifyPort delivery and signature guide.

Limitations and trade-offs

The official Shop API is the right choice for commerce support, but it requires custom-scope approval, seller authorization, valid Shop credentials, and message-type handling. The webhook does not remove the need for history reconciliation or authorization lifecycle handling.

An unofficial interface cannot approve the Customer Service scope, provide Seller Center order data, reproduce TikTok’s Shop agent features, or guarantee official Shop reply behavior. Keep the two integration surfaces and their credentials isolated.

FAQ

Which event should a TikTok Shop Customer Service API webhook subscribe to?

Use NEW_MESSAGE for a message sent in a customer-service conversation. The corresponding notification body uses numeric type 14. NEW_CONVERSATION is a separate event and should not replace message intake.

How quickly must the webhook return a response?

TikTok documents a 200 response with an empty body within three seconds. Verify, durably enqueue, and acknowledge; run slower business logic asynchronously.

How should duplicate TikTok Shop webhook deliveries be handled?

Store tts_notification_id and message_id, use an idempotent write, and make retrying a job safe. Also retain conversation_id and index so you can detect ordering gaps rather than only suppress duplicates.

Can the webhook replace Get Conversation Messages?

No. TikTok’s webhook overview says not to rely completely on notifications. Use the history endpoint to reconcile missing or out-of-order messages and after worker downtime.

Is this the same as a general TikTok DM webhook?

No. It is an approved TikTok Shop buyer-support surface. Ordinary-account DMs and Shop customer-service conversations have different access, identities, data, and operating rules.

Next step

Use TikTok Shop’s official webhook configuration guide to configure NEW_MESSAGE, then complete the six-step acceptance test above. If you actually need ordinary-account inbound routing, verify the separate boundary in UnifyPort’s provider message-support matrix.

Sources

Official TikTok Shop sources checked on August 11, 2026: