tiktok-shop-webhooks

TikTok Shop Webhooks

When to Use This Skill

• How do I receive TikTok Shop webhooks?
• How do I verify TikTok Shop webhook signatures?
• How do I handle ORDER_STATUS_CHANGE or PACKAGE_UPDATE events?
• Why is my TikTok Shop webhook signature verification failing?
• Setting up TikTok Shop webhook handlers and event subscriptions

Verification (core)

TikTok Shop puts the signature in the Authorization header (no Bearer prefix) as a lowercase-hex HMAC-SHA256. The signed message is your app_key concatenated with the raw request body, keyed by your app_secret. Verify against the raw body exactly as received — don't JSON.parse first.

This is not the Standard Webhooks spec and is distinct from TikTok Shop's API request signing. There is no timestamp in the signature, so it offers no replay protection — dedupe on tts_notification_id and reconcile by polling.

const crypto = require('crypto');

// sign base = app_key + rawBody ; key = app_secret ; digest = lowercase hex
function verifyTikTokShop(rawBody, authHeader, appKey, appSecret) {
  const expected = crypto
    .createHmac('sha256', appSecret)
    .update(appKey + rawBody)          // rawBody: exact bytes received, as UTF-8
    .digest('hex');
  try {
    return crypto.timingSafeEqual(
      Buffer.from(authHeader || '', 'utf8'),
      Buffer.from(expected, 'utf8')
    );
  } catch {
    return false;                      // length mismatch = invalid
  }
}

Return HTTP 200 with an empty body within 3 seconds on success; return 401 to signal a rejected signature.

For complete handlers with route wiring, event dispatch, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/

Common Event Types

Subscribe to event types per shop in Partner Center (or via the Events API). Subscriptions are configured by event_type string (one callback URL per topic). The delivered payload carries a numeric type — TikTok Shop's docs state they do not publish a complete numeric mapping and warn: "Do not branch only on the numeric type; use the subscribed event_type context and the topic-specific payload schema." Only type: 1 (ORDER_STATUS_CHANGE) appears in the official sample payload. The most robust pattern is a distinct callback path per subscribed topic, so the route identifies the event.