Webhooks idempotentes para agências: assinatura, duplicatas e retentativas

Cada entrega é um POST com um envelope JSON com os campos delivery_id, event_id, version, instance_id, instance_name, event e data. Os cabeçalhos trazem X-ZapZap-Id (o delivery_id), X-ZapZap-Event e, quando a instância tem segredo, X-ZapZap-Signature no formato t=<unix>,v1=<hmac>.

O segredo (prefixo whsec_) é gerado quando você configura o webhook da instância e vem na resposta da configuração. A assinatura é um HMAC SHA-256, com esse segredo, sobre o texto t, um ponto e o corpo exato da requisição. Por isso o corpo tem de ser lido em bytes, antes de qualquer parse de JSON.

Recalcule o HMAC e compare com o v1 usando comparação em tempo constante. Rejeite com 401 se a assinatura não bater, e rejeite também quando o horário t estiver a mais de 5 minutos de distância do seu relógio, para barrar a reprodução de uma requisição antiga capturada. A tolerância recomendada no produto é de 5 minutos.

Um erro comum em Express é usar express.json() antes da rota: o corpo é reserializado e o HMAC não bate. Use express.raw() na rota do webhook, como no código abaixo, que foi executado localmente com assinatura válida, horário vencido e corpo adulterado, e deu verdadeiro, falso e falso.

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const SECRET = process.env.ZAPZAP_WEBHOOK_SECRET; // whsec_..., returned when you set the webhook
const TOLERANCE_S = 300;                          // reject anything older than 5 minutes
const seen = new Set();                           // production: table with a UNIQUE key (see SQL below)

export function validSignature(rawBody, header, nowS = Math.floor(Date.now() / 1000)) {
  const parts = Object.fromEntries(
    String(header || "").split(",").map((kv) => kv.split("=").map((s) => s.trim())),
  );
  const t = Number(parts.t);
  if (!Number.isFinite(t) || !parts.v1) return false;
  if (Math.abs(nowS - t) > TOLERANCE_S) return false;
  const expected = createHmac("sha256", SECRET).update(t + "." + rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(parts.v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

const app = express();
// raw body: the HMAC is computed over the exact bytes ZapZap sent, so do not use express.json() here
app.post("/webhook", express.raw({ type: "*/*", limit: "2mb" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!validSignature(raw, req.get("X-ZapZap-Signature"))) return res.sendStatus(401);
  const envelope = JSON.parse(raw);
  const key = envelope.event_id || envelope.delivery_id; // pick one key and keep it
  res.sendStatus(200);                                    // answer fast, work afterwards
  if (seen.has(key)) return;                              // duplicate: ignore
  seen.add(key);
  setImmediate(() => console.log("process", envelope.event, key));
});
app.listen(3000);

/* production dedupe (any SQL database):
   CREATE TABLE webhook_events (
     instance_id text NOT NULL, dedupe_key text NOT NULL,
     received_at timestamptz DEFAULT now(), payload jsonb,
     PRIMARY KEY (instance_id, dedupe_key));
   INSERT ... ON CONFLICT DO NOTHING; if 0 rows inserted, it was a repeat. */

O envelope traz delivery_id e event_id. Escolha uma chave e use sempre a mesma: a opção mais simples é event_id quando existir, caindo para delivery_id. Grave a chave numa tabela com restrição de unicidade por instância e chave. Se o INSERT não inserir nenhuma linha, é repetição e você ignora.

O teste de webhook da API usa event_id nulo e um delivery_id que começa com test_, então o seu código não deve tratar event_id nulo como erro. Para uma agência, a chave composta com instance_id evita colisão entre clientes e dá o isolamento: o evento de um cliente nunca mistura com o de outro.

Responda 200 assim que validar e gravar a chave, e processe o resto em segundo plano. Resposta lenta vira timeout, e timeout vira repetição. No lado da ZapZap, a primeira tentativa é imediata, e falhas entram numa fila de retentativas com intervalos crescentes (cerca de 2 minutos, 10 minutos e 1 hora, no código do produto), e depois da última tentativa o evento deixa de ser reenviado.

Por isso o seu painel deve ter um caminho de recuperação: a API lista as entregas recentes (GET /instances/{id}/webhook/deliveries) e os erros de webhook, o que ajuda a achar o que faltou depois de uma indisponibilidade. Veja a referência.

Um segredo por instância, guardado cifrado; um endpoint com a rota por cliente ou resolução pela instance_id; log da chave, do evento e do resultado; alerta quando a taxa de 401 sobe (sinal de segredo trocado ou de ataque); e testes com o POST /instances/{id}/webhook/test a cada deploy. Para montar isso com um agente de código, veja construa com IA e a página de agências com IA.

Lembre que o conteúdo recebido (texto de clientes finais) é entrada não confiável: nunca o execute nem o repasse sem validação para um agente com permissão de envio.