Verificar webhooks do TikTok: o cabeçalho de assinatura e como o validar
A API for Business do TikTok assina cada entrega de webhook num cabeçalho Tiktok-Signature com a forma t=<segundos unix>,s=<hex>, em que s é um HMAC-SHA256 do valor de t, de um ponto e do corpo do pedido, com a chave do segredo da aplicação de programador. Para validar uma entrega, recalcule esse HMAC sobre o corpo bruto tal como foi recebido, compare-o com s em tempo constante e rejeite um t desatualizado.
A easyCoexistence valida a assinatura do TikTok em cada evento de comentário que a aplicação recebe e reencaminha os eventos de comentários da conta ligada para o seu endpoint HTTPS, assinados em X-EC-Signature com um segredo só para essa conta.
As duas partes de Tiktok-Signature: a marca temporal Unix da entrega, em segundos, e a assinatura que o TikTok gerou para ela.
O acceptableDelay do exemplo Node do TikTok, que recusa uma entrega corretamente assinada mais antiga do que esse valor.
Cabeçalho que transporta o ID único de cada entrega, que o TikTok pede aos recetores que registem para resolução de problemas.
Tipo de evento dos webhooks de menções, cujo guia de subscrição aponta para a mesma validação de assinatura.
A parte da assinatura do cabeçalho X-EC-Signature da easyCoexistence, um HMAC-SHA256 de t, um ponto e o corpo bruto.
Como é o cabeçalho Tiktok-Signature?
Duas partes, separadas por uma vírgula: t, a marca temporal 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; os nomes de cabeçalhos HTTP não distinguem maiúsculas de minúsculas, pelo que convém lê-lo sem essa distinção, como já fazem a maioria das frameworks. Os outros cabeçalhos da entrega de exemplo do TikTok:
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: 202201120803530102451591650189C78Que bytes o TikTok assina?
O valor de t como texto, um ponto final e depois o corpo. O guia do TikTok chama a esta última parte uma cópia em JSON serializada do corpo do pedido, e o exemplo do TikTok em Node recria a cópia ao executar JSON.stringify sobre um objeto já analisado. Isso reproduz os bytes do TikTok apenas enquanto ambos os serializadores concordarem em espaçamento, ordem das chaves e escape; por isso, calcule-o sobre o corpo exatamente como chegou, antes de qualquer middleware JSON o ler.
Qual é a chave?
O segredo da aplicação de programador, que se encontra em My Apps, App Detail, Basic Information no portal de programadores do TikTok. É o valor que a aplicação já envia como secret para /business/webhook/update/ e como client_secret para os endpoints de token. Um só segredo assina as entregas de cada conta que autorizou a aplicação, pelo que o recetor não precisa de chave por conta, e nem o token de acesso nem o ID da aplicação entram no cálculo.
Como validar em Node.js?
Com node:crypto e o corpo bruto. A função abaixo separa o cabeçalho, recalcula o HMAC sobre t, o ponto final e os bytes do corpo, compara o resultado em tempo constante e depois verifica a idade de t. Recebe como argumento o nome da parte da assinatura, pelo que o mesmo código também valida as entregas reencaminhadas pela easyCoexistence, onde essa parte se chama v1 e a chave é o segredo de assinatura da conta:
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
});Ao fim de quanto tempo recusa uma entrega?
O TikTok deixa o limite ao recetor: calcule a diferença entre o relógio do servidor e t e decida se é tolerável, diz o guia. O exemplo em Node permite 5 segundos, um limite tão apertado que um servidor cujo relógio esteja alguns segundos desfasado pode recusar entregas genuínas; o código acima permite 300, a janela que a easyCoexistence pede aos recetores nos seus próprios reencaminhamentos. Meça a partir de t, a hora da entrega que a assinatura cobre, e não a partir de create_time do corpo, que marca quando o evento ocorreu. No exemplo do TikTok, t está um segundo depois de create_time.
O que deve o endpoint responder?
Um 200 assim que a assinatura estiver validada, com o trabalho feito depois, já que o TikTok trata qualquer outro estado como entrega falhada e volta a enviá-la. Para uma assinatura que não corresponde, o exemplo do TikTok responde com um código de estado 4xx e regista o cabeçalho x-tt-logid, que identifica o pedido se um problema for comunicado ao TikTok. client_key no corpo indica a aplicação de programador, pelo que compará-lo com o seu próprio ID de aplicação é uma segunda verificação barata.
Como se regista o URL de callback, e é validado?
Através de uma única chamada à API, e o TikTok não documenta nenhum pedido de desafio que teste primeiro o URL. POST /business/webhook/update/ recebe o app_id, o secret, um event_type e um 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 o URL registado para um tipo de evento. A prova de origem é a assinatura de cada entrega.
Pode validar o Tiktok-Signature nos eventos que a easyCoexistence reencaminha?
Não, e nada o exige. O TikTok assina essas entregas com o segredo da aplicação de programador própria da easyCoexistence, que nenhuma ferramenta nem API disponibiliza. A easyCoexistence valida essa assinatura à medida que cada evento chega, responde 401 a uma que falhe, ignora um corpo cujo client_key indique outra aplicação e, em seguida, assina o reencaminhamento para o seu endpoint em X-EC-Signature com o segredo de assinatura dessa conta ligada.
Como a easyCoexistence assina o que reencaminha?
No cabeçalho X-EC-Signature, t=<unix>,v1=<hex>, em que t é a hora do reencaminhamento e v1 o HMAC-SHA256 em hexadecimal de t, de um ponto e do corpo exatamente como enviado. A chave é o segredo de assinatura da conta, whsec_ seguido de 32 caracteres, usado por inteiro, com o prefixo. Dos cabeçalhos que a easyCoexistence define, só Content-Type e este existem, sem cabeçalho de evento, pelo que o nome do evento se lê em entry.event:
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 reencaminhamento seguinte. Chamar set_social_webhook_destination ou PUT /channels/{id}/webhook de novo devolve um segredo novo e retira o antigo de imediato; cada reencaminhamento é enviado uma só vez, pelo que um evento que o servidor recuse durante a troca fica perdido. Aceite os dois segredos durante alguns minutos enquanto o novo é implementado. Os eventos de estado sobre canais e publicações usam outro segredo, o que se encontra no painel, em Profile, Developers, e chegam com os cabeçalhos X-EC-Event e X-EC-Delivery, com novas tentativas durante cerca de 33 horas.
Erros comuns
- Validar um corpo que a framework já analisou. O middleware JSON entrega um objeto, e voltar a serializá-lo pode alterar os bytes do TikTok; leia o corpo bruto na rota do webhook.
- Responder 200 a uma entrega cuja assinatura falhou. O TikTok deixa de enviar um evento assim que vê um 200, pelo que um evento genuíno recusado por uma validação mal configurada fica perdido; um 4xx faz o TikTok repetir durante 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.
- Descodificar em Base64 o segredo da easyCoexistence ou cortar o prefixo whsec_. A chave HMAC é a cadeia inteira, exatamente como foi mostrada uma vez.
Defina o endpoint com set_social_webhook_destination a partir do Claude ou do ChatGPT, ou com PUT /channels/{id}/webhook. De US$ 9 até US$ 0.75 por ligação por mês, a descer à medida que acrescenta ligações, com os primeiros 3 dias gratuitos.
Perguntas frequentes
O que é x-tt-logid num webhook do TikTok?
Um cabeçalho que transporta o ID único de cada entrega. O TikTok pede aos recetores que o registem, pois identifica o pedido quando comunica um problema ao TikTok.
O TikTok envia um desafio para validar um novo URL de webhook?
Não documenta nenhum para a sua API for Business. A chamada /business/webhook/update/ regista o URL, e as entregas chegam depois com Tiktok-Signature para o seu servidor validar.
Porque é que a assinatura do meu webhook do TikTok nunca coincide?
Verifique a entrada e a chave: o HMAC tem de abranger t, um ponto e o corpo bruto tal como foi recebido, usar o segredo da aplicação e ser comparado com o valor a seguir a s=, e não com o cabeçalho inteiro.
Como valido eventos do TikTok reencaminhados pela easyCoexistence?
Com X-EC-Signature e o segredo de assinatura mostrado quando definiu o destino: recalcule o HMAC-SHA256 sobre t, um ponto e o corpo bruto, compare-o com v1 e recuse um t com mais de 5 minutos.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em