Outgoing webhooks send inbox events to your URL in real time (Enterprise plan feature; set them up in Settings → Webhooks).
Events
| Event | When |
|---|---|
mensagem.recebida | the contact sent a message |
mensagem.enviada | the business sent one (inbox, agent, campaign, automation or phone) |
mensagem.status | delivered, read or failed |
conversa.atribuida | the conversation got an assignee |
conversa.aguardando_humano | the AI agent handed off to the team |
conversa.resolvida / conversa.reaberta | status changed |
Format
{ "id": "…", "evento": "mensagem.recebida", "criado_em": "2026-10-16T12:00:00Z", "workspace_id": "…", "tentativa": 1, "dados": { … } }Verify the signature
Header X-ConverZAP-Assinatura: t=<unix>,v1=<hex>, where v1 = HMAC-SHA256(secret, "<t>.<raw body>"). Reject if t is more than 5 minutes off.
import crypto from "node:crypto";
function verify(body, header, secret) {
const p = Object.fromEntries(header.split(",").map((x) => x.split("=")));
if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${p.t}.${body}`).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));
}Reply 2xx within 10 s. Otherwise we retry after 1 min, 5 min, 30 min, 2 h, 6 h and 12 h; 410 stops retries. Deliveries may repeat and arrive out of order: dedupe by id.