Integration reference
Webhook delivery expectation model
Ordering assumptions, duplicate delivery, replay windows, and observability signals for event-driven integrations.
01
Expectation model
Design handlers assuming duplicates, delay, and reorder—not single perfect delivery.
| Signal | Healthy pattern | Investigate when |
|---|---|---|
| Verification failures | Low stable baseline | Spike after deploy/rotation |
| Duplicate rate | Stable with idempotent no-ops | Duplicates cause side effects |
| Recency lag | Within internal SLO you define | Growing stuck lifecycles |
| Out-of-order | Safe no-ops/buffer | Crash loops / retry exhaustion |
- Retries are normal. Webhook delivery is at-least-once. Design consumers to tolerate duplicates and out-of-order arrivals where possible.
- Asynchronous by design. Payers, chains, and your servers operate on different clocks. UI and finance should not assume synchronous finality.
- Eventual consistency. API reads, webhooks, and portal views may briefly diverge during transitions. Reconciliation jobs exist to converge truth.
Walkthroughs: /operations