Novas tentativas e falhas

Quando o seu endpoint não aceita uma requisição de webhook, o Emailit guarda os eventos e tenta de novo seguindo um cronograma que dura pouco mais de três dias. Esta página lista esse cronograma, explica os e-mails que o Emailit envia e quando ele desativa um endpoint, e mostra como inspecionar e reenviar requisições com falha.

O que conta como falha

Uma requisição falha quando o seu endpoint:

• Retorna qualquer status fora de 200–299, incluindo redirecionamentos (3xx).
• Não responde em até 30 segundos.
• Não pode ser alcançado: erros de DNS, conexões recusadas, erros de TLS ou uma URL que resolve para um endereço IP privado.

A falha vale para o lote inteiro: todos os eventos da requisição recebem novas tentativas juntos.

Cronograma de novas tentativas

Após cada tentativa com falha, o Emailit espera antes de tentar de novo:

Se a tentativa 11 falhar, a requisição é marcada como Failed e não recebe mais novas tentativas automáticas. Você ainda pode reenviá-la por 7 dias.

Cada tentativa é assinada de novo com um timestamp novo. Os eventos que chegam enquanto requisições anteriores aguardam uma nova tentativa são enviados em lotes próprios, então um evento problemático não bloqueia os mais recentes.

E-mails de notificação

O Emailit envia um e-mail ao proprietário do workspace em dois momentos:

Desativação automática

Se um webhook passar 3 dias sem nenhuma entrega bem-sucedida desde a requisição com falha mais antiga, o Emailit o desativa na próxima tentativa com falha. Na prática, isso acontece por volta da 11ª tentativa da primeira requisição com falha, ou antes, se novos eventos continuarem falhando.

Enquanto um webhook está desativado:

• Novos eventos não entram na fila dele. Eles continuam sendo registrados no fluxo de eventos.
• As requisições que aguardavam uma nova tentativa ficam pendentes e são retomadas quando você o ativa.
• A página do webhook mostra o status Disabled.

Para reativá-lo, selecione Enable webhook no menu de ações do webhook ou chame Atualizar um webhook com {"enabled": true}. Retry failed e tentar de novo uma única requisição também ativam o webhook.

A aba Requests

Abra um webhook em Email API›Webhooks para ver a aba Requests dele, com as mais recentes primeiro:

Filtre por Status code, Event ou Created. Os eventos de teste de Send test não aparecem aqui.

Em uma requisição Failed, selecione View para abrir Failure reason: o código de status que o seu endpoint retornou (0 quando não houve resposta HTTP), quando a requisição foi criada e quando falhou, e os primeiros 2.000 caracteres do corpo da resposta.

Reenviar requisições com falha

Você pode reenviar requisições marcadas como Failed cuja última falha ocorreu nos últimos 7 dias. As requisições reenviadas voltam para Pending e começam um novo ciclo de novas tentativas a partir da tentativa 1. A entrega não é instantânea: a próxima rodada de entregas as pega em poucos segundos.

Tentar de novo uma requisição

Na aba Requests, selecione Retry em uma linha com falha. O botão só aparece em requisições com falha dos últimos 7 dias.

O endpoint da API é Tentar de novo uma requisição, POST /v2/webhooks/{id}/requests/{request_id}/retry, que retorna {"retried": 1, "id": "whr_…"}. Ele só aceita requisições marcadas como Failed e retorna 400 para as demais. Os IDs de requisição (whr_…) não são listados por nenhum endpoint público, então, para automação pela API, use Retry failed.

Tentar de novo as requisições com falha

Abra o menu de ações do webhook e selecione Retry failed. Todas as requisições que falharam nos últimos 7 dias voltam para a fila, e o painel mostra “Queued 3 failed request(s) for retry” com a contagem real, ou “No failed requests in the last 7 days”.

Pela API, chame Tentar de novo as requisições com falha:

curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e/retry-failed \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

{ "retried": 42 }

Recuperar-se de uma interrupção

1. Corrija o endpoint. Use View em uma requisição com falha para ver o que o seu endpoint retornou.

2. Confirme que ele funciona. Use Send test no menu de ações, ou Enviar um evento de teste pela API, e confira se a resposta é 2xx.

3. Ative o webhook se o Emailit o tiver desativado.

4. Reenvie as falhas. Selecione Retry failed para colocar de volta na fila todas as requisições que falharam nos últimos 7 dias. As requisições ainda marcadas como Attempting recebem novas tentativas no próprio cronograma.

5. Preencha as lacunas. Os eventos que aconteceram enquanto o webhook estava desativado nunca entraram na fila, e as falhas com mais de 7 dias não podem ser reenviadas. Leia-os com a API de eventos para o período afetado e processe os que estiverem faltando.

Como as novas tentativas reenviam lotes inteiros, torne o seu handler idempotente: armazene cada event_id e ignore os que você já processou. Consulte Requisições de webhook.

Retenção

As requisições de webhook seguem o período de retenção de Logs, então as linhas mais antigas somem da aba Requests com o tempo.

Veja também