Webhooks

Eventos de entrega na URL do seu sistema, assinados com HMAC-SHA256.

Cadastrar

POST/api/v1/webhooks

{
  "url": "https://sua-app.com/webhooks/allyonemail",
  "events": ["delivered", "bounced", "complained"],
  "description": "Produção"
}

Exige escopo admin (ou o painel). A URL precisa ser pública — endereços internos são recusados.

Guarde o secret agora

O secret aparece completo só nesta resposta; depois as leituras o mostram mascarado. Para ver um valor novo, use POST /api/v1/webhooks/:id/rotate-secret.

Eventos

Evento	Quando
`delivered`	O servidor do destinatário aceitou a mensagem.
`deferred`	Falha temporária; o AllyOneMail vai tentar de novo. Não é bounce.
`bounced`	O destino recusou a mensagem.
`complained`	O destinatário marcou como spam (feedback loop do provedor).
`opened`	Abertura registrada pelo pixel.
`clicked`	Clique num link rastreado (`url` no payload).
`unsubscribed`	Descadastro pelo link ou pelo cabeçalho de um clique.
`blocked`	Envio barrado antes de sair (destinatário suprimido ou bloqueado).
`domain_verified`	Domínio passou na verificação de DNS.
`ip_paused`	IP de envio pausado por reputação.
`reputation_dropped`	Queda forte de reputação de um IP (traz taxas de bounce e reclamação).
`billing_threshold_reached`	Consumo do mês cruzou um limite de alerta do plano.
`incident_escalated`	Incidente de entregabilidade escalado (alerta operacional).

Entregas repetidas

O mesmo evento pode chegar mais de uma vez — por retentativa, ou porque delivered é emitido quando o servidor de envio aceita a mensagem e de novo na confirmação final de entrega. Deduplique por X-AllyOneMAIL-Id, ou por message_id + event.

Payload

{
  "event": "bounced",
  "message_id": "msg_a1b2c3",
  "to": "cliente@destino.com",
  "provider": "gmail",
  "response": "550 5.1.1 The email account that you tried to reach does not exist",
  "timestamp": "2026-10-01T13:00:00.000Z",
  "client_id": "c1f0..."
}

Todo payload traz client_id. Eventos de envio trazem message_id, to, provider e, conforme a origem, from, response (a resposta do servidor do destinatário) e latency_ms. opened e unsubscribed trazem message_id, to e timestamp; clicked traz também url.

Validar a assinatura

X-AllyOneMAIL-Event: bounced
X-AllyOneMAIL-Sig: sha256=<hex>

Cabeçalhos X-AllyOneMAIL-Event (o evento) e X-AllyOneMAIL-Sig: sha256= + HMAC-SHA256 do corpo bruto com o secret. Calcule sobre os bytes recebidos, antes do parse. O cabeçalho X-AllyOneMAIL-Id identifica a entrega e se repete nas retentativas.

const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
// compare em tempo constante com o header X-AllyOneMAIL-Sig

Entrega e falhas

Sucesso é qualquer 2xx em até 10 segundos; redirecionamentos não são seguidos.
Em falha, até 3 tentativas: na hora, depois de ~1 minuto e depois de ~2 minutos.
Toda tentativa fica em GET /api/v1/webhooks/:id/deliveries (guardadas por 90 dias). Reenvie uma entrega com POST /api/v1/webhooks/:id/deliveries/:deliveryId/retry.
Depois de 10 entregas seguidas falhando nas 3 tentativas, o webhook é pausado. Corrija o endpoint e reative com PATCH /api/v1/webhooks/:id.
Responda 2xx rápido e processe numa fila do seu lado.

Testar

POST/api/v1/webhooks/:id/test

Dispara um delivered sintético para a sua URL, assinado com o mesmo secret.