# Novas tentativas e falhas

> Como o Emailit faz novas tentativas de requisições de webhook com falha, quando envia e-mails para você e desativa um endpoint, e como inspecionar e reenviar requisições com falha.

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:

| Tentativa | Espera após a tentativa anterior | Tempo desde a primeira tentativa |
| --- | --- | --- |
| 1 | Enviada poucos segundos após o evento | 0 |
| 2 | 5 minutos | 5 minutos |
| 3 | 30 minutos | 35 minutos |
| 4 | 2 horas | 2 horas e 35 minutos |
| 5 | 5 horas | 7 horas e 35 minutos |
| 6 | 12 horas | 19 horas e 35 minutos |
| 7 | 12 horas | 1 dia e 7 horas |
| 8 | 12 horas | 1 dia e 19 horas |
| 9 | 12 horas | 2 dias e 7 horas |
| 10 | 12 horas | 2 dias e 19 horas |
| 11 | 12 horas | 3 dias e 7 horas |

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](#resend-failed-requests) 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:

| Quando | E-mail |
| --- | --- |
| Uma requisição falha pela terceira vez (cerca de 35 minutos após a primeira falha) | O webhook está falhando. Enviado uma vez por incidente. Você só recebe outro depois de uma entrega bem-sucedida seguida de novas falhas, ou após 4 dias. |
| O webhook é desativado automaticamente | O webhook foi desativado, com o último código de status. |

## 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](/pt/docs/logs/events/).
- 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](/pt/docs/api-reference/webhooks/update/) 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:

| Coluna | Descrição |
| --- | --- |
| **Event type** | O evento da requisição. |
| **Event ID** | O ID `evt_`, o mesmo valor que o seu endpoint recebe como `event_id`. |
| **Created** | Quando a requisição foi colocada na fila. |
| **Attempts** | Quantas tentativas de entrega falharam até agora. |
| **Status** | **Pending** (ainda não tentada), **Attempting** (falhou pelo menos uma vez e receberá novas tentativas), **Delivered** ou **Failed** (as novas tentativas se esgotaram). |

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](/pt/docs/api-reference/webhooks/retry-request/), `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](/pt/docs/api-reference/webhooks/retry-failed/):

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

```json
{ "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](/pt/docs/api-reference/webhooks/test/) 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](/pt/docs/logs/events/#reconcile-missed-webhook-events) 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](/pt/docs/webhooks/webhook-requests/#duplicates).

## 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.

| | Pay as you go | Pro | Business | Custom |
| --- | --- | --- | --- | --- |
| Retenção dos logs de requisições | 7 dias | 30 dias | 30 dias | Flexível |

## Veja também

  - [Requisições de webhook](/pt/docs/webhooks/webhook-requests/)
  - [Eventos](/pt/docs/logs/events/)

---
Fonte: https://emailit.com/pt/docs/webhooks/retries-and-failures/