Todos os artigos
Engenharia

Webhooks: eventos, assinaturas e novas tentativas

Quais eventos o Postline envia, como verificar cada solicitação e o que acontece quando seu endpoint está fora do ar.

Eventos

Assine cada endpoint em 1 a 20 destes tipos de evento:

  • email.accepted
  • email.queued
  • email.sent
  • email.delivered
  • email.deferred
  • email.bounced
  • email.complained
  • email.opened
  • email.clicked
  • email.received
  • email.suppressed
  • domain.verified
  • domain.failed

Entrada da assinatura

HMAC-SHA256(secret, timestamp + "\0" + event_id + "\0" + body)

Postline-Timestamp: 1784743200
Postline-Event-Id: evt_…
Postline-Signature: v1=…

Solicitação e conteúdo

POST https://example.com/hooks/postline
Content-Type: application/json
Postline-Event-Id: evt_3f2a9c…
Postline-Timestamp: 1784743200
Postline-Signature: v1=5d41402abc4b2a76…

{
  "id": "evt_3f2a9c…",
  "type": "email.delivered",
  "created_at": "2026-11-05T12:00:00Z",
  "data": {
    "email_id": "msg_01J…",
    "recipient": "user@example.net",
    "provider": "gmail",
    "smtp_response": "250 2.0.0 OK"
  }
}

Requisitos do receptor

  • Calcule a assinatura a partir do corpo bruto exato da requisição.
  • Compare as assinaturas em tempo constante.
  • Rejeite timestamps fora da sua janela permitida.
  • Armazene o event_id e processe cada evento uma única vez.
  • Não presuma que os eventos chegam na ordem do ciclo de vida.

Controles de saída

A criação de endpoint exige HTTPS. Alvos privados, loopback, link-local, de metadados, com credenciais embutidas e internos são bloqueados e resolvidos novamente no momento da conexão. Redirecionamentos não são seguidos. A entrega usa timeouts e tentativas de retentativa limitados.

Tempo limite e novas tentativas

Qualquer resposta 2xx confirma o evento. Tempo limite (15 s), erro de rede ou outro status contam como falha. O Postline faz até 6 tentativas: a primeira e novas tentativas após 1 min, 5 min, 30 min, 2 h e 8 h. Cada tentativa fica no registro de entregas e qualquer entrega pode ser reenviada manualmente pela API ou pelo painel.