ConectZap · Documentação

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

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}.