Configura endpoints en Configuración → Webhooks. Cada endpoint tiene una URL, un secreto y la lista de eventos a los que se suscribe.

Eventos

Evento	Cuándo se envía
`conversation.started`	Se abre una conversación nueva en el widget.
`conversation.handoff`	El agente escala a una persona (por intención, horario, presupuesto o error técnico).
`conversation.resolved`	La conversación se cierra, de forma automática o por una persona.
`ticket.status_changed`	Un ticket cambia de estado.
`budget.exceeded`	El costo de IA del mes superó el presupuesto de la cuenta; el agente pasa a escalar a humano.

Formato

{
  "id": "0192f1c3-...",
  "event": "conversation.handoff",
  "tenant_id": "0192f0aa-...",
  "created_at": "2026-09-01T15:04:05.000Z",
  "data": { "conversation_id": "0192f1b9-...", "reason": "intent" }
}

Cabeceras:

Cabecera	Contenido
`x-talkhero-event`	Nombre del evento.
`x-talkhero-delivery`	Id único de la entrega (para deduplicar).
`x-talkhero-timestamp`	Milisegundos Unix en el momento del envío.
`x-talkhero-signature`	`sha256=<HMAC_SHA256(secreto, timestamp + "." + cuerpo)>`

Verificar la firma

Calcula el HMAC sobre timestamp + "." + cuerpo crudo con el secreto del endpoint y compáralo en tiempo constante. Rechaza timestamps con más de 5 minutos de diferencia para evitar repeticiones.

import crypto from "node:crypto";

export function verifyTalkHero(req, secret) {
  const timestamp = req.headers["x-talkhero-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${req.rawBody}`).digest("hex");
  const given = req.headers["x-talkhero-signature"] ?? "";
  return expected.length === given.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given));
}

Reintentos

Responde 2xx en menos de 10 segundos. Cualquier otra respuesta o un timeout provoca reintentos con espera exponencial (30 s, 1 min, 2 min, 4 min, 8 min), hasta 6 intentos. El estado de cada entrega (pending, retrying, delivered, failed) queda registrado en tu cuenta.

Los eventos pueden llegar más de una vez: usa x-talkhero-delivery para deduplicar.