> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtpayroll/webhooks/retry-e-garantias.md).

# Retry e Garantias de Entrega

Como o GTPayroll retenta a entrega de um webhook e o que o seu endpoint precisa tolerar.

## Política de retry

| Tentativa | Intervalo após falha |
| --------- | -------------------- |
| 1ª        | 1 minuto             |
| 2ª        | 5 minutos            |
| 3ª        | 30 minutos           |
| 4ª        | 2 horas              |
| 5ª        | 6 horas              |

Após 5 tentativas sem sucesso, o evento é marcado como **cancelado**.

## Critérios de sucesso e falha

| Resposta                              | Comportamento                                              |
| ------------------------------------- | ---------------------------------------------------------- |
| **2xx**                               | Sucesso — evento entregue                                  |
| **3xx, 5xx**, timeout ou erro de rede | Falha retentável — retry agendado                          |
| **4xx**                               | Falha permanente — evento **cancelado na hora**, sem retry |

{% hint style="warning" %}
Qualquer 4xx (400, 401, 403, 404…) cancela o evento. Responda `2xx` assim que receber a notificação.
{% endhint %}

## Ciclo de vida do evento

```
QUEUED → [envio] → SUCCESS
                  → FAILURE → [retry 1] → SUCCESS
                                         → FAILURE → [retry 2] → ...
                                                                → CANCELLED (limite atingido)
                  → CANCELLED (4xx)
```

## Entrega e ordem

* A entrega é **at-least-once**: por causa do retry, o mesmo evento pode chegar mais de uma vez.
* **Não há garantia de ordem**: um evento mais recente pode chegar antes da reentrega de um anterior.

## Idempotência

Trate duplicatas e eventos fora de ordem no seu endpoint. Decida pelo:

* **`eventType`** — o que aconteceu;
* **estado atual do recurso** no seu sistema (ex.: contrato já `COMPLETED` — ignore a reentrega de um evento anterior);
* **`sourceId`** (quando o evento traz) ou campos/timestamps do payload, para identificar duplicatas e reentregas tardias.
