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
| Evento | Cuándo sale |
|---|---|
item.updated | Cada vez que un ítem cambia de estado o de resultado |
message.status | Cambia 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.closed | Se cierra una conversación con ítems; reason dice cómo: resolved_by_ai, closed_by_agent, auto_timeout o agent_inactivity |
conversation.handoff | Una conversación con ítems pasa a una persona del equipo (no se cierra) |
integration.ping | Cuando 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": []
}
}
}
- En
item.updated,data.itemes el ítem completo, igual que enGET /v1/items/{type}/{external_id}(el ejemplo lo muestra recortado), ydata.item_eventdice qué cambió en ese evento y quién lo hizo (agent,api,userosystem). - En
integration.ping,dataes{ "message": "ping" }y los campos del ítem vienen ennull.
Headers
| Header | Qué trae |
|---|---|
X-TalkAI-Event-Id | El mismo event_id del cuerpo |
X-TalkAI-Event | El nombre del evento |
X-TalkAI-Timestamp | Segundos desde 1970 (epoch) del momento del intento |
X-TalkAI-Signature | sha256=<hex> con el secreto actual |
X-TalkAI-Signature-Key-Id | El id del secreto con el que se firmó (el panel lo muestra como Id del secreto actual) |
X-TalkAI-Signature-Previous | Durante las 24 h siguientes a una rotación: la firma con el secreto anterior |
X-TalkAI-Signature-Previous-Key-Id | El id del secreto anterior |
Authorization | Bearer <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.
X-TalkAI-Timestamp y X-TalkAI-Signature.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).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
- Solo una respuesta 2xx cuenta como entregado. Cualquier otro código, un timeout (8 segundos) o un error de red se reintenta.
- No se siguen redirecciones: un 301 o 302 cuenta como fallo. Registrá la URL final.
- Se reintenta a 1, 5, 15 y 60 minutos; si el último intento también falla, el aviso queda como fallido. Para recuperarlo, consultá
GET /v1/items?updated_since=. - Los avisos no llegan necesariamente en orden. Usá
updated_atdel ítem para quedarte con el estado más nuevo. - Un mismo aviso puede llegar más de una vez (por ejemplo, si tu sistema lo procesó pero tardó en responder). Todos los intentos traen el mismo
event_id: guardalo y descartá los repetidos. - Si la organización deja de tener integraciones, los avisos quedan en pausa y salen cuando se reactivan.
https. No se aceptan direcciones internas ni privadas.