Garantias de Ordem e Idempotência de Eventos

A comunicação de eventos entre o Yzex Connect e os endpoints integrados de parceiros adota garantias rigorosas de entrega e resiliência.

Semântica de Entrega At-Least-Once

O despachador de webhooks opera sob o modelo de Entrega no Mínimo Uma Vez (At-Least-Once Delivery). Em casos de instabilidade de rede ou respostas lentas (HTTP timeout), o sistema retransmitirá a notificação.

Idempotência no Consumidor

Para mitigar processamentos duplicados decorrentes de retries de rede:

  1. Cada evento carrega um identificador global único event_id (formato ULID).

  2. O sistema consumidor deve manter uma tabela de chaves de idempotência processadas recentemente.

  3. Se um event_id já tiver sido consumido com sucesso dentro de uma janela de 24 horas, a aplicação deve responder HTTP 200 OK imediatamente sem reexecutar a lógica de negócio associada.