Webhooks: avisos firmados

Para quién es: quien desarrolla el sistema que recibe los avisos de TalkAI

Para qué sirve

Cada vez que cambia un ítem, TalkAI le hace un POST a la URL que registraste en Configuración > Integraciones > Webhook. Así tu sistema se entera al momento de que un cliente confirmó, canceló o pidió un cambio, sin tener que preguntar.

Eventos

EventoCuándo sale
item.updatedCada vez que un ítem cambia de estado o de resultado
message.statusCambia el estado de un mensaje de una conversación con ítems, incluida la plantilla inicial de la campaña: sent, delivered, read o failed (con el código de error de WhatsApp)
conversation.closedSe cierra una conversación con ítems; reason dice cómo: resolved_by_ai, closed_by_agent, auto_timeout o agent_inactivity
conversation.handoffUna conversación con ítems pasa a una persona del equipo (no se cierra)
integration.pingCuando tocás Probar webhook en el panel (no hace falta marcarlo en los eventos; el webhook tiene que estar activo)

Los tres eventos de mensaje y conversación traen item_external_ids con los ítems involucrados. Las conversaciones sin ítems no generan avisos.

Si el contacto manda archivos, item.updated trae en item_event.attachments solo los adjuntos nuevos de ese cambio, cada uno con su sha256 y un link que vence a las 24 h. Si el link venció, consultá el ítem: cada lectura devuelve links nuevos.

Si el webhook está desactivado o sin URL, los avisos no se guardan para después: usá GET /v1/items?updated_since= para ponerte al día (ver Referencia de la API).

El cuerpo

Todos los eventos comparten la misma envoltura:

{
  "event_id": "3b6f0c1e-...",
  "event": "item.updated",
  "occurred_at": "2026-11-19T12:06:42.120Z",
  "flow": "confirmar_pedidos",
  "campaign_id": "6f1c...",
  "campaign_external_id": "camp-2026-11-20",
  "conversation_id": "9a2e...",
  "contact_external_id": "cliente-77",
  "item_type": "pedido",
  "item_external_id": "P-1001",
  "data": {
    "item": { "type": "pedido", "external_id": "P-1001", "status": "resolved", "result": { "respuesta": "confirma" } },
    "item_event": {
      "type": "status_changed",
      "actor": { "type": "agent", "id": "..." },
      "from_status": "in_progress",
      "to_status": "resolved",
      "result_diff": { "respuesta": { "from": null, "to": "confirma" } },
      "motivo": null,
      "attachments": []
    }
  }
}

Headers

HeaderQué trae
X-TalkAI-Event-IdEl mismo event_id del cuerpo
X-TalkAI-EventEl nombre del evento
X-TalkAI-TimestampSegundos desde 1970 (epoch) del momento del intento
X-TalkAI-Signaturesha256=<hex> con el secreto actual
X-TalkAI-Signature-Key-IdEl id del secreto con el que se firmó (el panel lo muestra como Id del secreto actual)
X-TalkAI-Signature-PreviousDurante las 24 h siguientes a una rotación: la firma con el secreto anterior
X-TalkAI-Signature-Previous-Key-IdEl id del secreto anterior
AuthorizationBearer <tu token>, solo si lo cargaste en el panel

También van Content-Type: application/json y User-Agent: TalkAI-Webhooks/1.

Verificar la firma

La firma es un HMAC-SHA256, con tu secreto whsec_... como clave, de la cadena "<timestamp>.<cuerpo>": el valor de X-TalkAI-Timestamp, un punto y el cuerpo tal cual llegó, byte por byte. Calculala sobre el cuerpo crudo, antes de parsear el JSON: si lo parseás y lo volvés a serializar, la firma no coincide.

➡️
Paso:Leé el cuerpo crudo y los headers X-TalkAI-Timestamp y X-TalkAI-Signature.
➡️
Paso:Rechazá el aviso si el timestamp está a más de 5 minutos de tu reloj (protege contra reenvíos de avisos viejos).
➡️
Paso:Calculá sha256= + HMAC-SHA256 en hexadecimal de timestamp + "." + cuerpo con tu secreto y comparalo con X-TalkAI-Signature en tiempo constante. Si no coincide y llegó X-TalkAI-Signature-Previous, probá con esa (y tu secreto anterior).
➡️
Paso:Si la firma es válida, respondé 2xx rápido y procesá el aviso después.

Ejemplo en Node.js con Express:

const crypto = require('crypto');
const express = require('express');

const app = express();
const SECRET = process.env.TALKAI_WEBHOOK_SECRET; // whsec_...
const yaProcesados = new Set(); // en tu sistema, una tabla con event_id

function firmaValida(rawBody, ts, firma, secreto) {
  if (!firma || !secreto) return false;
  const esperada = 'sha256=' + crypto.createHmac('sha256', secreto).update(ts + '.' + rawBody).digest('hex');
  const a = Buffer.from(esperada);
  const b = Buffer.from(firma);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/talkai', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const ts = req.get('X-TalkAI-Timestamp');
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(400).end();

  const ok = firmaValida(rawBody, ts, req.get('X-TalkAI-Signature'), SECRET)
    || firmaValida(rawBody, ts, req.get('X-TalkAI-Signature-Previous'), process.env.TALKAI_WEBHOOK_SECRET_ANTERIOR);
  if (!ok) return res.status(401).end();

  const evento = JSON.parse(rawBody);
  if (yaProcesados.has(evento.event_id)) return res.status(200).end(); // repetido: ya lo tenemos
  yaProcesados.add(evento.event_id);

  res.status(200).end(); // primero responder, después procesar
  if (evento.event === 'item.updated') {
    const item = evento.data.item;
    console.log(item.type, item.external_id, item.status, item.result);
  }
});

app.listen(3000);

Rotar el secreto

Desde el panel, Rotar secreto genera uno nuevo y lo muestra una sola vez. Durante las 24 h siguientes cada aviso va firmado con el nuevo en X-TalkAI-Signature y con el anterior en X-TalkAI-Signature-Previous, así podés actualizar tu sistema sin perder avisos. Pasadas las 24 h, solo vale el nuevo. La primera vez, el secreto se genera solo al guardar el webhook con su URL.

Entrega y reintentos

⚠️
Atención:La URL tiene que ser pública y con https. No se aceptan direcciones internas ni privadas.