Skip to content

B47: webhooks do Resend — entregue, bounce e spam - #145

Merged
tecrodrigocastro merged 2 commits into
feat/b34-tarefasfrom
feat/b47-webhooks-resend
Nov 19, 2026
Merged

tecrodrigocastro merged 2 commits into
feat/b34-tarefasfrom
feat/b47-webhooks-resend

Conversation

@tecrodrigocastro

Copy link
Copy Markdown
Member

Closes #96

Empilhado sobre o #144 (B34): a base é feat/b34-tarefas, porque os dois mexem no documento de arquitetura. Quando o #144 entrar, o GitHub troca a base para main sozinho.

Hoje um envio fica sent quando o Resend aceita a mensagem. Com este PR, a plataforma passa a saber se o e-mail chegou, voltou ou foi marcado como spam, e para de mandar para endereço que derruba a reputação do domínio.

Como funciona

  • Endpoint: POST /api/v1/webhooks/resend, com throttle:webhooks e sem login.
  • Assinatura Svix: HMAC-SHA256 de {svix-id}.{svix-timestamp}.{corpo} com o segredo whsec_… de RESEND_WEBHOOK_SECRET (ADR 0006). Aceita várias assinaturas no cabeçalho, compara em tempo constante e só aceita timestamp a até 5 minutos de agora.
    • Sem segredo configurado, com assinatura errada ou fora da janela, a resposta é 401 e nada muda. Os eventos rejeitados não entram em email_webhook_events.
  • Idempotência: um registro por svix-id em email_webhook_events, com unique no banco. A mesma entrega repetida responde duplicate: true e não repete o efeito.
  • Edição (ADR 0007): o transport do Laravel grava o id do Resend como Message-ID, e o envio já guardava esse valor em provider_message_id. O webhook acha o envio por esse id e a edição vem do envio. O que o corpo do webhook manda nunca é usado como edição, e há teste com edition_id forjado no corpo. Envio desconhecido fica registrado como ignored.

Status de entrega

Evento Efeito
email.delivered status delivered + delivered_at
email.bounced permanente status bounced + bounced_at + motivo, e bloqueia o endereço
email.bounced temporário só registra o motivo em provider_detail; não bloqueia
email.delivery_delayed só registra o motivo; não bloqueia
email.complained status complained + complained_at, e bloqueia o endereço

Bloqueio do endereço

  • Fica em email_suppressions, por edição, com o motivo e o envio que causou. É auditado como notifications.address_suppressed.
  • Vale para todo e-mail da edição, inclusive transacional: o envio novo nasce suppressed, com o motivo em provider_detail.
  • O envio que já estava na fila quando o endereço foi bloqueado também não sai, porque o job confere antes de enviar.
  • Reenviar para endereço bloqueado é recusado, com a mensagem de onde liberar.
  • A organização lista em GET /emails/suppressions?q= e libera em DELETE /emails/suppressions/{id}, auditado como notifications.suppression_lifted. Se o endereço continuar inválido, o próximo bounce bloqueia de novo.
  • A lista de envios (GET /emails/deliveries) ganhou status_label, provider_detail, delivered_at, bounced_at e complained_at, e o filtro por status aceita os novos.

A tela do painel (status novos e liberar endereço) entra com a A23 (Comunicação), que é a tela de e-mails.

Critérios de aceite

  • Assinatura inválida ou timestamp fora da janela é rejeitado e nada muda.
  • O mesmo evento recebido duas vezes não duplica efeito.
  • Endereço com bounce permanente não recebe novo envio (suppressed) até a organização liberar.
  • Bounce temporário não bloqueia o endereço.

Para configurar em produção

No painel do Resend, crie um webhook para https://<api>/api/v1/webhooks/resend com os eventos email.delivered, email.bounced, email.delivery_delayed e email.complained, e coloque o segredo whsec_… em RESEND_WEBHOOK_SECRET.

Test plan

  • composer check passa: Pint, PHPStan nível 8, Rector e Pest com 1060 testes (2 pulados, de sandbox). São 8 testes novos em ResendWebhookTest.
  • Documento de arquitetura atualizado: 69 tabelas, 260 rotas, webhook e bloqueio na página de operação.
  • Teste com um webhook real do Resend (sandbox): não rodei, falta configurar o endpoint numa URL pública.

…o endereço

Assinatura Svix verificada com janela de 5 minutos, um registro por
svix-id, edição descoberta pelo envio e bounce permanente ou reclamação
bloqueando o endereço na edição até a organização liberar.
@tecrodrigocastro tecrodrigocastro self-assigned this Nov 19, 2026
@tecrodrigocastro
tecrodrigocastro merged commit 7098127 into feat/b34-tarefas Nov 19, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant