Iniciar sesiónEmpezar prueba gratis
easyCoexistence APIs oficiales

Verificar webhooks de TikTok: el encabezado de firma y cómo comprobarlo

La API for Business de TikTok firma cada entrega de webhook en un encabezado Tiktok-Signature con la forma t=<segundos unix>,s=<hex>, donde s es un HMAC-SHA256 del valor de t, un punto y el cuerpo de la petición, con la clave del secreto de la app de desarrollador. Para verificarla, recalcula ese HMAC sobre el cuerpo crudo tal como llega, compara con s en tiempo constante y rechaza un t antiguo.

easyCoexistence verifica la firma de TikTok en cada evento de comentario que recibe su app, y luego reenvía los eventos de comentarios de la cuenta conectada a tu endpoint HTTPS, firmados en X-EC-Signature con un secreto solo para esa cuenta.

t and s

Las dos partes de Tiktok-Signature: la marca de tiempo Unix en segundos de la entrega y la firma que TikTok generó para ella.

5 seconds

El acceptableDelay del ejemplo en Node de TikTok, que rechaza una entrega correctamente firmada si es más antigua que ese valor.

x-tt-logid

Encabezado que lleva el ID único de cada entrega, que TikTok pide registrar para la resolución de problemas.

BRAND_MENTION

Tipo de evento para los webhooks de menciones, cuya guía de suscripción remite a la misma verificación de firma.

v1

La parte de firma del encabezado X-EC-Signature de easyCoexistence, un HMAC-SHA256 de t, un punto y el cuerpo crudo.

¿Cómo es el encabezado Tiktok-Signature?

Dos partes separadas por una coma: t, la marca de tiempo Unix en segundos de esa entrega, y s, la firma, de 64 caracteres hexadecimales. Las páginas de TikTok escriben el nombre como TikTok-Signature, Tiktok-Signature y tiktok-signature; los nombres de encabezado HTTP no distinguen mayúsculas, así que léelo sin importar el caso, como ya hacen la mayoría de frameworks. Los demás encabezados de la entrega de ejemplo de 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

¿Qué bytes firma TikTok?

El valor de t como cadena, un punto y luego el cuerpo. La guía de TikTok llama a esa última parte una copia JSON serializada del cuerpo de la petición, y su ejemplo en Node reconstruye la copia ejecutando JSON.stringify sobre un objeto ya parseado. Eso reproduce los bytes de TikTok solo mientras ambos serializadores coincidan en espaciado, orden de claves y escape; por eso conviene calcular el HMAC sobre el cuerpo exactamente como llegó, antes de que cualquier middleware JSON lo lea.

¿Qué secreto es la clave?

El secreto de la app de desarrollador, que está en Mis apps, Detalle de la app, Información básica en el portal de desarrolladores de TikTok. Es el valor que la app ya envía como secret a /business/webhook/update/ y como client_secret a los endpoints de token. Un solo secreto firma las entregas de cada cuenta que autorizó la app, así que el receptor no necesita una clave por cuenta, y ni el token de acceso ni el ID de la app intervienen.

¿Cómo se verifica en Node.js?

Con node:crypto y el cuerpo crudo. La función de abajo separa el encabezado, recalcula el HMAC sobre t, el punto y los bytes del cuerpo, compara el resultado en tiempo constante y después comprueba la antigüedad de t. Recibe el nombre de la parte de firma como argumento, así que el mismo código también verifica los reenvíos de easyCoexistence, donde esa parte se llama v1 y la clave es el secreto de firma de la cuenta:

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

¿Qué antigüedad puede tener una entrega antes de rechazarla?

TikTok deja el límite en manos del receptor: calcula la diferencia entre tu reloj y t, dice su guía, y decide si es tolerable. Su ejemplo en Node permite 5 segundos, un margen tan ajustado que un reloj de servidor desfasado unos segundos podría rechazar entregas auténticas; el código de arriba permite 300, la ventana que easyCoexistence pide a los receptores para sus propios reenvíos. Mide desde t, el momento de la entrega que cubre la firma, no desde create_time del cuerpo, que marca cuándo ocurrió el evento. En el ejemplo de TikTok, t cae un segundo después de create_time.

¿Qué debe responder el endpoint?

Un 200 en cuanto la firma sea válida, con el trabajo hecho después, ya que TikTok considera cualquier otro estado como entrega fallida y la reenvía. Ante una firma que no coincide, el ejemplo de TikTok responde con un estado 4xx y registra el encabezado x-tt-logid, que identifica la petición si reportas un problema a TikTok. client_key en el cuerpo indica la app de desarrollador, así que compararlo con tu propio ID de app es una segunda comprobación barata.

¿Cómo se registra la URL de callback y se verifica?

Con una sola llamada a la API, y TikTok no documenta ninguna petición de verificación que pruebe antes la URL. POST /business/webhook/update/ recibe el app_id, el secret, un event_type y una callback_url HTTPS: VIDEO para eventos de publicación, COMMENT para comment.update y, en la Mentions API, BRAND_MENTION para brand.mention.event. Los tres llegan firmados de la misma forma, y GET /business/webhook/list/ muestra la URL registrada para cada tipo de evento. La prueba de origen es la firma de cada entrega.

¿Se puede comprobar Tiktok-Signature en los eventos que reenvía easyCoexistence?

No, y no hace falta. TikTok firma esas entregas con el secreto de la app de desarrollador propia de easyCoexistence, que ninguna herramienta ni API entrega. easyCoexistence verifica esa firma al llegar cada evento, responde 401 a la que falla, ignora un cuerpo cuyo client_key nombra otra app y luego firma su reenvío hacia ti en X-EC-Signature con el secreto de firma de esa cuenta conectada.

¿Cómo firma easyCoexistence lo que reenvía?

En el encabezado X-EC-Signature, t=<unix>,v1=<hex>, donde t es el momento del reenvío y v1 el HMAC-SHA256 en hexadecimal de t, un punto y el cuerpo exactamente como se envió. La clave es el secreto de firma de la cuenta, whsec_ seguido de 32 caracteres, usado completo, con el prefijo incluido. De sus propios encabezados, easyCoexistence solo envía Content-Type y este, sin encabezado de evento, así que lee el nombre del evento en 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))

¿Qué pasa cuando se reemplaza el secreto de firma?

El nuevo secreto firma desde el siguiente reenvío. Llamar otra vez a set_social_webhook_destination o a PUT /channels/{id}/webhook devuelve un secreto nuevo y retira el anterior de inmediato, y cada reenvío se envía una sola vez, así que un evento que tu servidor rechace durante el cambio se pierde. Acepta ambos secretos durante unos minutos mientras se despliega el nuevo. Los eventos de estado sobre canales y publicaciones usan otro secreto, el que está en Dashboard, Profile, Developers, y llegan con los encabezados X-EC-Event y X-EC-Delivery, reintentados durante unas 33 horas.

Errores comunes

  • Verificar un cuerpo que el framework ya parseó. El middleware JSON entrega un objeto, y volver a serializarlo puede cambiar los bytes de TikTok; lee el cuerpo crudo en la ruta del webhook.
  • Responder 200 a una entrega cuya firma falló. TikTok deja de enviar un evento en cuanto ve un 200, así que una auténtica rechazada por una verificación mal configurada se pierde; un 4xx hace que TikTok reintente hasta por 72 horas.
  • Comparar firmas con ===, como hace el ejemplo de TikTok. Una comparación en tiempo constante como timingSafeEqual no revela cuántos caracteres de una firma falsa coincidieron.
  • Decodificar en base64 el secreto de easyCoexistence o quitarle el prefijo whsec_. La clave HMAC es la cadena completa, exactamente como se mostró una vez.
Hacerlo con EasyCoexistence

Configura el endpoint con set_social_webhook_destination desde Claude o ChatGPT, o con PUT /channels/{id}/webhook. Desde US$ 9 hasta US$ 0.75 por conexión al mes, que baja al añadir conexiones, con los primeros 3 días gratis.

Preguntas frecuentes

¿Qué es x-tt-logid en un webhook de TikTok?

Un encabezado que lleva el ID único de cada entrega. TikTok pide registrarlo, porque identifica la petición cuando reportas un problema a TikTok.

¿TikTok envía un desafío para verificar una nueva URL de webhook?

TikTok no documenta ninguno para su API for Business. La llamada a /business/webhook/update/ registra la URL, y luego las entregas llegan con Tiktok-Signature para que tu servidor la compruebe.

¿Por qué mi firma de webhook de TikTok nunca coincide?

Revisa la entrada y la clave: el HMAC debe cubrir t, un punto y el cuerpo crudo tal como llegó, usar el secreto de la app, y compararse con el valor después de s= y no con el encabezado completo.

¿Cómo verifico eventos de TikTok reenviados por easyCoexistence?

Con X-EC-Signature y el secreto de firma que se muestra al configurar el destino: recalcula el HMAC-SHA256 sobre t, un punto y el cuerpo crudo, compara con v1 y rechaza un t de más de 5 minutos.

Sigue leyendo

Conecta tu primer canal en dos minutos.

Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.

  • 3 días gratis
  • Cancela cuando quieras
  • Solo APIs oficiales
  • Monitorizado 24/7

Verificado el