Webhooks

Los webhooks le permiten reflejar los eventos de AskAIs Customer Service en sus propios sistemas — CRM, analítica, Slack, cualquier cosa que hable HTTP.

Crear un webhook

Vaya a Ajustes → Webhooks → Nuevo webhook. Elija los eventos, pegue su URL, guarde. Obtendrá un secreto que se usa para firmar las cargas útiles.

Tipos de evento

• conversation.created
• conversation.updated — estado, prioridad, asignación
• conversation.resolved
• message.created — cualquier mensaje, cualquier remitente
• contact.created
• contact.updated

Formato de la carga útil

POST https://your-app.com/webhooks/singlink
Content-Type: application/json
X-SingLink-Event: message.created
X-SingLink-Signature: sha256=ab12cd34...
X-SingLink-Timestamp: 1747300800

{
  "id": "evt_01HX...",
  "type": "message.created",
  "tenantId": "tnt_01HX...",
  "data": { /* event-specific payload */ }
}

Verificar firmas

Calcule el HMAC-SHA256 sobre timestamp + "." + rawBody con el secreto del webhook. Compárelo con la cabecera X-SingLink-Signature (de forma segura frente al tiempo).

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(req, secret) {
  const ts = req.headers["x-singlink-timestamp"];
  const sig = req.headers["x-singlink-signature"];
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(ts + "." + req.rawBody)
    .digest("hex");
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Reintentos

Reintentamos las respuestas que no son 2xx con retroceso exponencial: 1s, 10s, 1m, 10m, 1h. Tras 5 intentos, el evento se marca como fallido; puede ver los fallos en el panel de administración.

Ping de prueba

Cada webhook tiene un botón Enviar prueba que publica un evento webhook.ping ficticio. Útil para verificar que su endpoint acepta firmas antes de ponerlo en producción.