Webhooks

O NextChat avisa o seu sistema a cada evento.

Em vez de consultar a API o tempo todo, cadastre um endereço e o NextChat envia um POST a cada evento. Cadastre pela API (permissão webhooks:manage) ou em Configurações → Integrações.

curl -X POST "$NEXTCHAT_API/integrations/webhooks" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Meu ERP","url":"https://erp.exemplo.com.br/nextchat","events":["message.received","attendance.closed"]}'

A resposta traz o segredo de assinatura whsec_… uma única vez: guarde-o. Até 20 endereços por empresa. Teste com POST /integrations/webhooks/{id}/test e veja as entregas em GET /integrations/webhooks/{id}/deliveries.

O que chega

{ "id": "evento-uuid", "type": "attendance.opened", "created_at": "2026-10-15T10:30:00Z", "tenant_id": "…", "data": { "…": "objeto do evento" } }

Cabeçalhos: X-NextChat-Event, X-NextChat-Event-Id, X-NextChat-Delivery, X-NextChat-Timestamp (segundos) e X-NextChat-Signature: sha256=<hex>.

Verificar a assinatura

A assinatura é o HMAC-SHA256, com o segredo, de "<timestamp>.<corpo bruto>". Rejeite se o timestamp tiver mais de 5 minutos.

import { createHmac, timingSafeEqual } from 'node:crypto';
const ok = (secret, ts, raw, sig) => {
  const mine = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${raw}`).digest('hex');
  return mine.length === sig.length && timingSafeEqual(Buffer.from(mine), Buffer.from(sig));
};

import hmac, hashlib
def ok(secret, ts, raw: bytes, sig: str) -> bool:
    mine = "sha256=" + hmac.new(secret.encode(), ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mine, sig)

Entrega e novas tentativas

Responda 2xx em até 8 segundos. Senão, o NextChat tenta de novo depois de 30 s, 2 min, 10 min, 1 h e 6 h. Depois de 10 entregas seguidas que falharam de vez, o endereço é desativado (reative com PATCH {active: true}). As entregas ficam 14 dias. Pode haver entrega repetida: use X-NextChat-Event-Id para ignorar as duplicadas.

Endpoints