Iniciar sessãoIniciar teste gratuito
easyCoexistence APIs oficiais

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.

t and s

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

5 seconds

O acceptableDelay do exemplo Node do TikTok, que recusa uma entrega corretamente assinada mais antiga do que esse valor.

x-tt-logid

Cabeçalho que transporta o ID único de cada entrega, que o TikTok pede aos recetores que registem para resolução de problemas.

BRAND_MENTION

Tipo de evento dos webhooks de menções, cujo guia de subscrição aponta para a mesma validação de assinatura.

v1

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:

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

Que 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:

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
});

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:

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 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.
Fazer isto com a EasyCoexistence

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