Envelope (típico)
TODO: chaves adicionais (código, correlation_id) se existirem na implementação — a origem mostra o mínimo.
Códigos HTTP (mapa geral)
| Código | Significado | Ação |
|---|---|---|
200 | Sucesso em leitura / confirmação de webhook de entrada (parceiro) | Siga a operação. |
201 | Criação de recurso | Guarde o id e externalId. |
400 | Validação de payload | Corrija o corpo. |
401 | Autenticação | Conferir Bearer e validade/escopo do token. |
404 | Não encontrado | Conferir parâmetros, ambiente e o UUID usado. |
409 | Conflito (ex.: externalId duplicado) | Outro externalId ou recuperar o recurso existente. |
422 | Regra de negócio | Ajuste valor, prazo ou pré-condições. |
500 | Erro interno | Retentativas (com cuidado). |
Retentativas
- 5xx ou timeout em leitura (
GET) ou leitura semelhante: use backoff exponencial com teto, sem martelar a API. - 4xx (fora de rate limit) em escrita: não retente sem corrigir o payload.
TODO: rate limit (429, Retry-After) — a origem não cita; confirmar com a implementação do gateway.
Divergência entre webhook e GET /.../{id}
- Trate o webhook como at-least-once; valide a assinatura e deduplique.
- Se a consulta mostrar o estado “à frente” do último evento processado, use o estado idempotente e reconcile logs.
- Em
PROVIDER_RESULT_UNKNOWNouRECONCILIATION_REQUIRED, use o guia de reconciliação operacional.
Falhas do seu endpoint de notificação
- Após validar a assinatura, responda 2xx rapidamente. Erros 5xx do seu lado alimentam retentativas com backoff (fila, conforme a origem).
- Handlers devem ser idempotentes.