Webhooks
Os webhooks enviam eventos ao seu backend no momento em que acontecem — uma mensagem foi entregue, um link foi clicado, um contato se descadastrou. Cada payload é assinado para que você possa confiar nele, e as entregas que falham são repetidas com backoff, então uma breve indisponibilidade nunca perde um evento.
O que você vai precisar
- Um endpoint HTTPS público para receber POSTs
- Uma chave de API ou acesso de administrador para registrar o webhook
Registre um endpoint
- 1
Abra Configurações → Webhooks
Ou chame POST /v1/workspaces/{workspace_id}/webhooks. Informe a sua URL HTTPS e escolha os eventos que você quer.
- 2
Guarde o segredo de assinatura
Cada webhook tem um segredo, exibido na criação. Você vai usá-lo para verificar cada requisição recebida.
- 3
Adicione cabeçalhos personalizados (opcional)
Anexe cabeçalhos (ex.: um token de autenticação) que o Climails vai enviar a cada entrega ao seu endpoint.
Eventos que você pode assinar
- E-mail — email.delivered, email.bounce, email.complaint, email.unsubscribe, email.opened, email.clicked.
- SMS — sms.delivered, sms.failed.
- Contatos — contact.subscribed, contact.unsubscribed, contact.changed.
- Campanhas — campaign.finished.
Verifique a assinatura
Cada requisição carrega X-Senderbox-Timestamp e X-Senderbox-Sig. Recompute o HMAC e compare — rejeite tudo o que não bater e rejeite timestamps antigos para impedir replays.
// signature = HMAC_SHA256(secret, timestamp + "." + rawBody)
import crypto from "node:crypto";
function verify(rawBody, headers, secret) {
const ts = headers["x-senderbox-timestamp"];
const sig = headers["x-senderbox-sig"]; // "sha256=<hex>"
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(ts + "." + rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}Retentativas e falhas
Retorne um 2xx rapidamente para confirmar. Se o seu endpoint der erro ou tempo esgotado, o Climails repete com backoff crescente: 30s, 2m, 10m, 1h, 6h, 24h.
- Após 6 tentativas falhas, a entrega é descartada.
- Um 4xx (exceto 408 e 429) é tratado como terminal e não é repetido — corrija o endpoint e ele retomará no próximo evento.
- Os endpoints são protegidos contra SSRF: endereços internos/privados são recusados.
Perguntas frequentes
Como verifico que um webhook é realmente do Climails?
Recompute o HMAC-SHA256 sobre timestamp + "." + corpo bruto com o segredo do webhook e compare com X-Senderbox-Sig. Use uma comparação de tempo constante.
O que acontece se meu servidor estiver fora do ar?
As entregas são repetidas com backoff (30s → 24h) ao longo de até 6 tentativas, então uma indisponibilidade curta não perde eventos.
Por que meu webhook parou de repetir imediatamente?
Uma resposta 4xx (que não seja 408/429) é tratada como erro permanente. Corrija o handler; novos eventos retomam a entrega.
Comece a enviar em minutos
Crie uma conta gratuita, conecte seu domínio e alcance seu público em todos os canais — sem cartão de crédito.
Plano gratuito para sempre · Sem cartão de crédito · Pronto em minutos