EntrarComeçar teste grátis
easyCoexistence APIs oficiais

Verificar webhooks do TikTok: o cabeçalho de assinatura e como checá-lo

A API for Business do TikTok assina cada entrega de webhook em um cabeçalho Tiktok-Signature no formato t=<segundos unix>,s=<hex>, em que s é um HMAC-SHA256 do valor de t, de um ponto e do corpo da requisição, com o segredo do app de desenvolvedor como chave. Para verificar, recalcule esse HMAC sobre o corpo bruto como foi recebido, compare com s em tempo constante e rejeite um t desatualizado.

O easyCoexistence verifica a assinatura do TikTok em cada evento de comentário que o app dele recebe e, então, encaminha os eventos de comentário da conta conectada para o seu endpoint HTTPS, assinados em X-EC-Signature com um segredo exclusivo dessa conta.

t and s

As duas partes de Tiktok-Signature: o timestamp Unix da entrega, em segundos, e a assinatura que o TikTok gerou para ela.

5 seconds

O acceptableDelay do exemplo em Node.js do TikTok, que recusa uma entrega corretamente assinada mais antiga que isso.

x-tt-logid

Cabeçalho que traz o ID único de cada entrega, que o TikTok pede que os receptores registrem para resolução de problemas.

BRAND_MENTION

Tipo de evento dos webhooks de menção, cujo guia de assinatura aponta para a mesma verificação de assinatura.

v1

A parte da assinatura do cabeçalho X-EC-Signature do easyCoexistence, um HMAC-SHA256 de t, um ponto e o corpo bruto.

Como é o cabeçalho Tiktok-Signature?

Duas partes, separadas por vírgula: t, o timestamp Unix em segundos dessa entrega, e s, a assinatura, com 64 caracteres hexadecimais. As páginas do TikTok escrevem o nome como TikTok-Signature, Tiktok-Signature e tiktok-signature; nomes de cabeçalho HTTP não diferenciam maiúsculas de minúsculas, então leia de forma insensível a caixa, como a maioria dos frameworks já faz. Os outros cabeçalhos da entrega de exemplo do TikTok:

Headers from TikTok's sample delivery
content-type: application/json;charset=UTF-8
user-agent: tiktok-webhook
tiktok-signature: t=1641974633,s=dc023ece112b3a07d809896fd929928a132168d95d2a2e43aab0105fbb291df8
webhook-schema-version: v1.0
x-tt-logid: 202201120803530102451591650189C78

Quais bytes o TikTok assina?

O valor de t como string, um ponto e o corpo. O guia do TikTok chama essa última parte de cópia em JSON serializado do corpo da requisição, e o exemplo em Node.js reconstrói a cópia executando JSON.stringify sobre um objeto já parseado. Isso reproduz os bytes do TikTok apenas enquanto os dois serializadores concordarem em espaçamento, ordem das chaves e escape, então calcule o hash do corpo exatamente como chegou, antes que qualquer middleware de JSON o leia.

Qual segredo é a chave?

O segredo do app de desenvolvedor, encontrado em My Apps, App Detail, Basic Information no portal de desenvolvedores do TikTok. É o valor que o app já envia como secret para /business/webhook/update/ e como client_secret para os endpoints de token. Um único segredo assina as entregas de cada conta que autorizou o app, então um receptor não precisa de chave por conta, e nem o token de acesso nem o ID do app participam.

Como verificar no Node.js?

Com node:crypto e o corpo bruto. A função abaixo separa o cabeçalho, recalcula o HMAC sobre t, o ponto e os bytes do corpo, compara o resultado em tempo constante e depois verifica a idade de t. Ela recebe o nome da parte da assinatura como argumento, então o mesmo código também verifica os encaminhamentos do easyCoexistence, em que essa parte se chama v1 e a chave é o segredo de assinatura da conta:

Node.js and Express: TikTok's deliveries and easyCoexistence's forwards
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

// Tiktok-Signature reads t=<unix>,s=<hex>; X-EC-Signature reads t=<unix>,v1=<hex>.
function verifySignature(rawBody, header, secret, name, maxAgeSeconds = 300) {
  const parts = {};
  for (const item of String(header ?? "").split(",")) {
    const i = item.indexOf("=");
    if (i > 0) parts[item.slice(0, i).trim()] = item.slice(i + 1).trim();
  }
  const signature = parts[name];
  if (!/^\d+$/.test(parts.t ?? "") || !signature) return false;
  const expected = createHmac("sha256", secret)
    .update(parts.t + ".")
    .update(rawBody) // the bytes exactly as they arrived
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
  return Math.abs(Date.now() / 1000 - Number(parts.t)) <= maxAgeSeconds;
}

const app = express();

// TikTok to your own developer app: the app secret, part s
app.post("/webhooks/tiktok", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifySignature(req.body, req.get("tiktok-signature"), process.env.TIKTOK_APP_SECRET, "s")) {
    console.warn("TikTok signature rejected, x-tt-logid:", req.get("x-tt-logid"));
    return res.sendStatus(401);
  }
  res.sendStatus(200); // acknowledge first: TikTok retries anything but a 200
  enqueue(req.body.toString("utf8")); // its content field is itself a JSON string
});

// easyCoexistence to your endpoint: the account's whsec_ secret, part v1
app.post("/webhooks/easycoexistence", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifySignature(req.body, req.get("x-ec-signature"), process.env.EC_SIGNING_SECRET, "v1")) {
    return res.sendStatus(401);
  }
  res.sendStatus(200);
  enqueue(req.body.toString("utf8")); // platform, account_id, external_id, entry
});

Com que idade uma entrega pode ser recusada?

O TikTok deixa o limite por conta do receptor: calcule a diferença entre o seu relógio e t, diz o guia, e decida se ela é tolerável. O exemplo em Node.js aceita 5 segundos, tão apertado que um relógio de servidor com alguns segundos de diferença poderia recusar entregas legítimas; o código acima aceita 300, a janela que o easyCoexistence pede que os receptores usem nos próprios encaminhamentos. Meça a partir de t, o horário da entrega coberto pela assinatura, e não de create_time no corpo, que marca quando o evento ocorreu. No exemplo do TikTok, t cai um segundo depois de create_time.

O que o endpoint deve responder?

Um 200 assim que a assinatura conferir, com o trabalho feito depois, já que o TikTok trata qualquer outro status como entrega falha e a reenvia. Para uma assinatura que não confere, o exemplo do TikTok responde com status 4xx e registra o cabeçalho x-tt-logid, que identifica a requisição caso você reporte um problema ao TikTok. client_key no corpo identifica o app de desenvolvedor, então compará-lo com o ID do seu próprio app é uma segunda verificação barata.

Como a URL de callback é registrada, e ela é verificada?

Por uma única chamada de API, e o TikTok não documenta nenhuma requisição de desafio que teste a URL antes. POST /business/webhook/update/ recebe app_id, secret, um event_type e uma callback_url HTTPS: VIDEO para eventos de publicação, COMMENT para comment.update e, na Mentions API, BRAND_MENTION para brand.mention.event. Os três chegam assinados da mesma forma, e GET /business/webhook/list/ mostra a URL registrada para um tipo de evento. A prova de origem é a assinatura em cada entrega.

Dá para verificar Tiktok-Signature nos eventos que o easyCoexistence encaminha?

Não, e nada exige isso. O TikTok assina essas entregas com o segredo do app de desenvolvedor próprio do easyCoexistence, que nenhuma ferramenta ou API entrega. O easyCoexistence verifica essa assinatura conforme cada evento chega, responde 401 a uma que falhe, ignora um corpo cujo client_key identifique outro app e, então, assina o encaminhamento para você em X-EC-Signature com o segredo de assinatura daquela conta conectada.

Como o easyCoexistence assina o que encaminha?

No cabeçalho X-EC-Signature, t=<unix>,v1=<hex>, em que t é o horário do encaminhamento e v1 o HMAC-SHA256 em hexadecimal de t, um ponto e o corpo exatamente como enviado. A chave é o segredo de assinatura da conta, whsec_ seguido de 32 caracteres, usado inteiro, com o prefixo. Dos seus próprios cabeçalhos, o easyCoexistence define apenas Content-Type e este, sem cabeçalho de evento, então leia o nome do evento em entry.event:

A forwarded TikTok comment event, as sent
POST https://hooks.example.com/tiktok/
Content-Type: application/json
X-EC-Signature: t=1793318405,v1=<HMAC_SHA256_HEX>

{"platform":"tiktok","account_id":"<ACCOUNT_ID>","external_id":"<TIKTOK_OPEN_ID>","entry":{"event":"comment.update","create_time":1793318400,"content":{...}}}

v1 = hex(HMAC-SHA256(key = "whsec_<SECRET>", message = "1793318405." + raw body))

O que acontece quando o segredo de assinatura é substituído?

O novo segredo assina a partir do próximo encaminhamento. Chamar set_social_webhook_destination ou PUT /channels/{id}/webhook de novo retorna um segredo novo e aposenta o antigo imediatamente, e cada encaminhamento é enviado uma única vez, então um evento que o seu servidor recusar durante a troca se perde. Aceite os dois segredos por alguns minutos enquanto o novo é implantado. Eventos de status sobre canais e publicações usam outro segredo, o de Dashboard, Profile, Developers, e chegam com os cabeçalhos X-EC-Event e X-EC-Delivery, com repetições por cerca de 33 horas.

Erros comuns

  • Verificar um corpo que o framework já parseou. O middleware de JSON entrega um objeto, e serializá-lo de novo pode alterar os bytes do TikTok; leia o corpo bruto na rota do webhook.
  • Responder 200 a uma entrega cuja assinatura falhou. O TikTok para de enviar um evento assim que vê um 200, então uma entrega legítima recusada por uma verificação mal configurada se perde; um 4xx faz o TikTok repetir por até 72 horas.
  • Comparar assinaturas com ===, como faz o exemplo do TikTok. Uma comparação em tempo constante, como timingSafeEqual, não revela quanto de uma assinatura forjada coincidiu.
  • Decodificar em Base64 o segredo do easyCoexistence ou cortar o prefixo whsec_. A chave HMAC é a string inteira, exatamente como foi mostrada uma única vez.
Fazendo isso com o EasyCoexistence

Defina o endpoint com set_social_webhook_destination, pelo Claude ou pelo ChatGPT, ou com PUT /channels/{id}/webhook. De US$ 9 a US$ 0.75 por conexão por mês, com o valor caindo conforme você adiciona conexões, e os primeiros 3 dias grátis.

O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.

Perguntas frequentes

O que é x-tt-logid em um webhook do TikTok?

Um cabeçalho que traz o ID único de cada entrega. O TikTok pede que os receptores o registrem, pois ele identifica a requisição quando você reporta um problema ao TikTok.

O TikTok envia um desafio para verificar uma nova URL de webhook?

O TikTok não documenta nenhum para a API for Business. A chamada a /business/webhook/update/ registra a URL, e as entregas então chegam com Tiktok-Signature para o seu servidor verificar.

Por que minha assinatura de webhook do TikTok nunca confere?

Confira a entrada e a chave: o HMAC deve cobrir t, um ponto e o corpo bruto como foi recebido, usar o segredo do app e ser comparado com o valor depois de s= e não com o cabeçalho inteiro.

Como verifico eventos do TikTok encaminhados pelo easyCoexistence?

Com X-EC-Signature e o segredo de assinatura mostrado quando você definiu o destino: recalcule o HMAC-SHA256 sobre t, um ponto e o corpo bruto, compare com v1 e recuse um t com mais de 5 minutos.

Continue lendo

Conecte seu primeiro canal em dois minutos.

Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.

  • 3 dias grátis
  • Cancele quando quiser
  • Só APIs oficiais
  • Monitorado 24/7

Verificado em