Webhooks

Os webhooks permitem espelhar os eventos do AskAIs Customer Service em seus próprios sistemas — CRMs, analytics, Slack, qualquer coisa que fale HTTP.

Criando um webhook

Vá em Configurações → Webhooks → Novo webhook. Escolha os eventos, cole sua URL, salve. Você receberá um segredo usado para assinar as cargas úteis.

Tipos de evento

• conversation.created
• conversation.updated — status, prioridade, atribuição
• conversation.resolved
• message.created — qualquer mensagem, qualquer remetente
• contact.created
• contact.updated

Formato da 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 */ }
}

Verificando assinaturas

Calcule o HMAC-SHA256 sobre timestamp + "." + rawBody com o segredo do webhook. Compare com o cabeçalho X-SingLink-Signature (de forma segura quanto ao tempo).

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

Novas tentativas

Reenviamos respostas não-2xx com backoff exponencial: 1s, 10s, 1m, 10m, 1h. Após 5 tentativas, o evento é marcado como falho; você pode ver as falhas no admin.

Ping de teste

Cada webhook tem um botão Enviar teste que envia um evento webhook.ping fictício. Útil para verificar se seu endpoint aceita assinaturas antes de entrar em produção.