Webhooks
O ConectZap não guarda conversas. Mensagens recebidas, status de entrega e eventos de conexão
chegam ao seu sistema por webhook (ou pelo
tempo real). Cada evento é um POST com corpo JSON (esquema
Event na referência) para a URL https que
você cadastrou.
Cadastro e segredo
-
POST /v1/webhookscria o webhook para a empresa inteira ou para uma instância (instanceId) e escolhe os tipos de evento. Osecret(whsec_…) aparece só nessa resposta: guarde-o num cofre de segredos ou variável de ambiente. - A URL precisa ser
https, na porta 443, pública e sem usuário ou senha. -
POST /v1/webhooks/{webhookId}/rotate-secretgera um segredo novo. O anterior continua valendo por 24 h: nesse período cada entrega leva duas assinaturas. -
POST /v1/webhooks/{webhookId}/testenvia um eventowebhook.testassinado e devolve o diagnóstico (no máximo 1 a cada 10 s por webhook).
Cabeçalhos de cada entrega
| Cabeçalho | Conteúdo |
|---|---|
Content-Type |
application/json |
User-Agent |
ConectZap-Webhooks/1 |
ConectZap-Event-Id |
Id único do evento (evt_…). Use-o para deduplicar. |
ConectZap-Timestamp |
Epoch em segundos da tentativa. Rejeite se divergir do seu relógio em mais de 300 s (5 min). |
ConectZap-Signature |
v1=<hex(HMAC-SHA256(secret, "{timestamp}.{rawBody}"))>, refeita a cada
tentativa com o timestamp dela. Na rotação do segredo:
v1=<nova>,v1=<anterior>.
|
Verificar a assinatura (Node.js)
Verifique toda entrega antes de confiar no conteúdo. Três cuidados: assine sobre
o corpo cru (os bytes como chegaram, não o JSON reconvertido), compare em tempo
constante (timingSafeEqual) e recuse timestamps fora da janela de 5 min, o que impede
a reutilização de uma entrega capturada.
// verificar-assinatura.mjs — Node 18 ou mais novo, sem dependências.
import { createHmac, timingSafeEqual } from "node:crypto";
const JANELA_S = 300; // 5 min: rejeite timestamps mais velhos (ou mais adiantados) que isso.
/**
* Confere o cabeçalho ConectZap-Signature de uma entrega de webhook.
* - segredo: o whsec_… do webhook (guarde num cofre ou variável de ambiente, nunca no código);
* - cabecalhos: os cabeçalhos da requisição, com nomes em minúsculas (como req.headers do Node);
* - corpoBruto: o corpo EXATAMENTE como chegou (string ou Buffer), antes de qualquer JSON.parse;
* - agoraS: relógio atual em segundos (o padrão serve; o parâmetro existe para testes).
* Devolve true só se o timestamp estiver na janela e alguma assinatura v1 conferir.
*/
export function verificarAssinatura(
segredo,
cabecalhos,
corpoBruto,
agoraS = Math.floor(Date.now() / 1000),
) {
const timestamp = cabecalhos["conectzap-timestamp"];
const assinatura = cabecalhos["conectzap-signature"];
if (typeof timestamp !== "string" || !/^\d{1,15}$/.test(timestamp)) return false;
if (typeof assinatura !== "string") return false;
// Com Content-Type diferente de application/json, o express.raw não preenche o corpo (vem {}):
// recuse em vez de deixar o createHmac lançar.
if (typeof corpoBruto !== "string" && !Buffer.isBuffer(corpoBruto)) return false;
if (Math.abs(agoraS - Number(timestamp)) > JANELA_S) return false;
// HMAC-SHA256(segredo, "{timestamp}.{corpoBruto}")
const esperada = createHmac("sha256", segredo)
.update(`${timestamp}.`)
.update(corpoBruto)
.digest();
// Na rotação do segredo chegam duas assinaturas ("v1=<nova>,v1=<anterior>"): basta uma conferir.
return assinatura.split(",").some((parte) => {
const [versao, hex = ""] = parte.trim().split("=");
if (versao !== "v1" || !/^[0-9a-f]{64}$/.test(hex)) return false;
// Comparação em tempo constante: nunca compare assinaturas com === ou ==.
return timingSafeEqual(Buffer.from(hex, "hex"), esperada);
});
}
Este exemplo é o mesmo código que a nossa suíte de testes executa contra o assinador do ConectZap: ele aceita assinaturas reais e recusa corpo ou assinatura adulterados e timestamps de 6 min atrás.
Deduplicar, responder rápido e processar depois
A entrega é at-least-once: o mesmo evento pode chegar mais de uma vez (por exemplo,
quando o seu 2xx se perde na rede). Deduplique por ConectZap-Event-Id,
guardando os ids já processados por alguns dias. Responda 2xx em até 10 s e deixe o
trabalho pesado para uma fila sua.
// Exemplo com Express: o corpo precisa chegar CRU (express.raw), não já convertido em JSON.
import express from "express";
import { verificarAssinatura } from "./verificar-assinatura.mjs";
const app = express();
app.post("/webhooks/conectzap", express.raw({ type: "application/json" }), async (req, res) => {
if (!verificarAssinatura(process.env.CONECTZAP_WEBHOOK_SECRET, req.headers, req.body)) {
return res.sendStatus(401);
}
const idDoEvento = req.headers["conectzap-event-id"];
if (await jaProcessado(idDoEvento)) return res.sendStatus(200); // repetição: só confirme
await enfileirar(JSON.parse(req.body.toString("utf8"))); // processe depois, fora da requisição
await marcarProcessado(idDoEvento);
res.sendStatus(200); // responda 2xx em até 10 s
});
Retentativas
Qualquer resposta que não seja 2xx (inclusive redirecionamento 3xx, que
não é seguido) e tempo esgotado geram nova tentativa. São 10 tentativas no total, com atrasos de
30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h, 6 h e 8 h entre elas (jitter de ±20 %; cerca de 22 h
no total).
Esgotadas as tentativas, o evento é descartado: o ConectZap registra só os
metadados da falha (GET /v1/webhooks/{webhookId}/deliveries, últimos 7 dias, sem
payload) e emite webhook.failed para os outros canais.
Desativação
Um webhook que falha sem nenhum sucesso há mais de 3 dias é desativado (enabled: false, disabledReason: consecutive_failures). Ao desativar, as entregas pendentes são
descartadas sem novas tentativas e sem webhook.failed. Corrija o endpoint e reative
com PATCH /v1/webhooks/{webhookId} e {"enabled": true}.