Como funcionam os webhooks do Resend?

O fluxo de webhooks do Resend

O fluxo começa quando você cria um endpoint HTTPS público e o cadastra no Resend com os tipos de evento de que a sua aplicação precisa. Quando ocorre um evento correspondente, o Resend envia uma requisição POST com um payload JSON. O payload inclui um tipo, como email.sent, email.delivered, email.bounced ou email.complained, um horário de criação e dados específicos do evento. Direcione o processamento pelo campo type, em vez de presumir que todos os payloads têm o mesmo formato.

Verifique a requisição antes de processá-la

Leia a requisição como texto bruto e verifique-a com o segredo de assinatura do webhook e os cabeçalhos svix-id, svix-timestamp e svix-signature. Faça isso antes de fazer o parsing do payload ou de agir com base nele. Fazer o parsing do JSON e serializá-lo de novo pode alterar os bytes e fazer uma assinatura legítima falhar. Rejeite as requisições que não passarem na verificação e guarde o segredo de assinatura em um gerenciador de segredos ou em uma variável de ambiente protegida, e não no código-fonte.

Torne o tratamento de eventos idempotente

O Resend documenta entrega do tipo at-least-once (pelo menos uma vez), então o mesmo evento pode chegar ao seu endpoint mais de uma vez. Armazene o svix-id com uma restrição de unicidade e pule a lógica de negócio quando esse identificador já tiver sido processado. Também não dependa da ordem de chegada, porque novas tentativas e atrasos de rede podem reordenar os eventos. Use o valor created_at do evento quando a sequência importar e modele as mudanças de status de forma que um evento mais antigo não sobrescreva acidentalmente um estado mais recente.

Confirme rápido e processe com segurança

Retorne HTTP 200 depois que o evento for verificado e registrado de forma durável e, em seguida, faça o trabalho mais lento por meio de uma fila ou de um worker em segundo plano. Um timeout ou uma resposta sem sucesso gera uma nova tentativa de entrega, então handlers síncronos demorados criam duplicatas evitáveis. Separe a ingestão dos efeitos colaterais, como atualizar um registro de supressão, notificar o suporte ou registrar um bounce. Cada efeito colateral também deve ser seguro para repetir ou protegido pelo identificador de evento armazenado.

Teste novas tentativas, replays e recuperação de falhas

Teste o endpoint com tipos de evento representativos antes de ir para produção, incluindo assinaturas inválidas, identificadores duplicados, timestamps fora de ordem e falhas temporárias do banco de dados. O Resend tenta novamente as entregas que falharam seguindo um cronograma de backoff e permite fazer replay tanto das mensagens de webhook com falha quanto das bem-sucedidas. Use o replay para se recuperar após uma indisponibilidade ou para validar um código de handler atualizado, mas mantenha a deduplicação ativa para que a recuperação não repita efeitos colaterais visíveis para os clientes.

Perguntas que as equipes fazem

Fontes primárias

• Managing Webhooks — Resend (em inglês)
• Verify Webhooks Requests — Resend (em inglês)
• Retries and Replays — Resend (em inglês)
• Webhook Event Types — Resend (em inglês)