Evento, Entrega, Tentativa
Todo o envio se explica em três níveis, e confundi-los é a origem da maior parte das dúvidas sobre “o webhook chegou ou não chegou”.
Um exemplo antes das definições
Seção intitulada “Um exemplo antes das definições”A Padaria do Zé é um cliente seu, cadastrado como Consumer cliente-42, com dois endpoints: o
sistema de estoque e o ERP, os dois inscritos em pedido.pago.
Você publica um pedido.pago. Acontece o seguinte:
| Estoque | ERP | |
|---|---|---|
| Entrega | dlv_…A |
dlv_…B |
| Tentativa 1 | 200 em 180 ms |
503 |
| Tentativa 2, 30s depois | timeout | |
| Tentativa 3, 2 min depois | 200 em 640 ms |
|
| Situação | delivered |
delivered |
Um Evento, duas Entregas, quatro Tentativas. O evento está entregue quando cada Entrega dele está entregue, e cada uma anda no seu próprio ritmo, sem esperar a outra.
O fato que você publica em POST /v1/events: um tipo, um Consumer e um data com o que você
quiser mandar. É imutável. Não existe editar um evento publicado; se o fato mudou, publique
outro.
Entrega
Seção intitulada “Entrega”A obrigação de levar um Evento a um endpoint. O fan-out do evento cria uma Entrega por endpoint inscrito no tipo, mais uma por endpoint sem inscrição nenhuma, porque esse recebe todos os tipos.
A Entrega é a unidade que importa: é ela que tem situação (pending, retrying, delivered,
exhausted…), é ela que tem retry, e é ela que você reenvia quando algo deu errado. O
ciclo de vida mostra cada situação.
Tentativa
Seção intitulada “Tentativa”Uma execução HTTP de uma Entrega, com o resultado: status devolvido, duração, tipo de erro e o começo da resposta. Uma Entrega bem-sucedida de primeira tem uma Tentativa; uma que esgotou o cronograma tem nove.
As tentativas são o que você consulta para diagnosticar. “O endpoint devolveu 401 nas nove”
quase sempre quer dizer verificação de assinatura quebrada do lado de quem recebe.
Retry e replay não são a mesma coisa
Seção intitulada “Retry e replay não são a mesma coisa”As duas ações mandam de novo, e a diferença está no nível em que agem.
- Retry age numa Entrega: insiste naquela Entrega, para aquele endpoint. É o que você usa quando o endpoint estava fora do ar e voltou.
- Replay age no Evento: refaz o fan-out e cria Entregas novas para os endpoints inscritos agora. Um endpoint cadastrado depois do evento original também recebe.
Os detalhes estão em retry, replay e desativação automática.
No recebimento
Seção intitulada “No recebimento”A mesma estrutura, com outros nomes na ponta de entrada: a Mensagem recebida é o análogo do Evento, e ela gera uma Entrega por Destino da fonte. Entrega e Tentativa são exatamente as mesmas coisas.