Por que o meu endpoint de webhook foi desativado?

Este artigo explica por que o Emailit para de enviar eventos para um webhook, como encontrar o erro por trás disso e como recuperar os eventos que você perdeu.

Sintomas

• Você recebeu um e-mail do Emailit dizendo que o seu webhook está falhando e, mais tarde, outro dizendo que ele foi desativado.
• O webhook aparece como desativado em Email API›Webhooks, e os novos eventos não chegam mais ao seu endpoint.
• A aba Requests na página do webhook lista requisições com o status Failed e muitas tentativas.

Causa

O Emailit considera qualquer resposta 2xx um sucesso. Todo o resto conta como falha, incluindo:

• Códigos de status 4xx ou 5xx, por exemplo vindos da verificação de assinatura ou de falhas da aplicação.
• Nenhuma resposta em 30 segundos.
• Redirecionamentos. O Emailit não segue 301 nem 302, então uma URL http:// que redireciona para https://, ou a falta da barra no final, falha toda vez.
• Erros de DNS, de certificado TLS ou de conexão.

As requisições com falha são reenviadas após 5 minutos, 30 minutos, 2 horas, 5 horas e depois a cada 12 horas, até 11 tentativas. O Emailit envia um e-mail ao proprietário do workspace quando uma requisição falha pela terceira vez. Se o endpoint continuar falhando sem nenhuma entrega bem-sucedida por 3 dias, o webhook é desativado e o proprietário recebe outro e-mail.

Enquanto um webhook está desativado, os novos eventos não são colocados na fila para ele.

Solução

1. Encontre o erro. Abra o webhook e selecione a aba Requests. Abra uma requisição com falha para ver o Failure reason, o Status code e o corpo da resposta que o seu endpoint retornou.

2. Corrija o endpoint. Correções comuns:

   • Use a URL final, com https:// e o caminho exato, para que não haja redirecionamento.
   • Retorne 200 rapidamente e faça o trabalho demorado em um job em segundo plano, para ficar abaixo de 30 segundos.
   • Corrija a verificação de assinatura. Consulte Por que a assinatura do meu webhook não confere?.
   • Libere as requisições do Emailit no seu firewall, WAF ou proteção contra bots.

3. Teste. Escolha Send test, selecione um tipo de evento e confira se a caixa de diálogo mostra um status 2xx.

4. Reative e reenvie. Escolha Retry failed. Isso coloca de novo na fila todas as requisições com falha dos últimos 7 dias e reativa o webhook. Você também pode selecionar Enable webhook ou chamar Tentar de novo as requisições com falha.

5. Recupere os eventos do período em que ele ficou desativado. Os eventos criados enquanto o webhook estava desativado não foram colocados na fila. Busque-os com Listar eventos, filtrando por type e created_at.

Para tornar o seu handler resiliente, deixe-o idempotente com o campo event_id, porque um lote reenviado pode chegar duas vezes. Consulte Novas tentativas e falhas.

Ainda com problemas?

Fale com o suporte ou pergunte no Discord, informando o ID do webhook (wh_…) e o motivo da falha que aparece na aba Requests.