tiktok-webhooks

TikTok Webhooks

Webhooks from the TikTok for Developers platform (developers.tiktok.com) — Login Kit, Content Posting / Video Kit, and Data Portability. These are not TikTok Shop webhooks, which use a different portal and signature scheme — see tiktok-shop-webhooks.

When to Use This Skill

• How do I receive TikTok webhooks?
• How do I verify the TikTok-Signature header?
• Why is my TikTok webhook signature verification failing?
• How do I handle authorization.removed, video.upload.failed, video.publish.completed, or portability.download.ready events?
• How do I reject replayed TikTok webhook deliveries?

Verification (core)

TikTok has no webhook SDK — verify manually. The TikTok-Signature header looks like t=1633174587,s=<hex>. The signature is HMAC-SHA256(client_secret, "<t>.<raw_body>"), hex-encoded. Verify against the raw request body (don't JSON.parse first) and reject stale timestamps to block replay.

const crypto = require('crypto');

function verifyTikTokWebhook(rawBody, header, clientSecret, toleranceSec = 300) {
  if (!header || !clientSecret) return false;
  const parts = Object.fromEntries(
    header.split(',').map((kv) => kv.split('='))
  );
  const { t, s } = parts;
  if (!t || !s) return false;

  // Reject stale timestamps (no tolerance window is documented; 5 min is sane).
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(t));
  if (!Number.isFinite(age) || age > toleranceSec) return false;

  const raw = Buffer.isBuffer(rawBody) ? rawBody.toString('utf8') : rawBody;
  const expected = crypto
    .createHmac('sha256', clientSecret)
    .update(`${t}.${raw}`, 'utf8')
    .digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(s, 'hex'), Buffer.from(expected, 'hex'));
  } catch {
    return false; // length mismatch = invalid
  }
}

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

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