Retry and replay

Webhook delivery retries happen outside trade and payout DB transactions.

Default schedule

• attempt 1: immediate after event commit
• attempt 2: +1 minute
• attempt 3: +5 minutes
• attempt 4: +15 minutes
• attempt 5: +1 hour
• attempt 6: +6 hours
• after max attempts: dead_letter

What causes retry

• request timeout
• DNS failure
• TLS failure
• network error
• HTTP 429
• HTTP 5xx
• other non-2xx except terminal 410

What ends delivery

• any 2xx response -> sent
• HTTP 410 -> dead_letter immediately
• max attempts reached -> dead_letter

Timeout behavior

• default endpoint timeout: 5 seconds
• operator can set timeout per endpoint record
• response body stored only as short sample for debugging

Replay semantics

• replay targets existing delivery record
• replay creates another delivery attempt for same outbox event
• replay does not create new business event
• replay does not mutate order, ticket, result, wallet operation, payout, refund, or redemption state
• replay stays operator-scoped
• replay of any previously delivered 2xx response may produce another accepted callback, not only replay after HTTP 200; dedupe by the original event_id

Receiver design rules

• return 2xx only after durable commit on operator side
• return 5xx for transient failure that should retry
• use 410 only when event should never be retried for that endpoint
• do not rely on exactly-once delivery
• retain the event_id dedupe record for as long as dashboard replay is possible; permanent inbox retention is safest
• acknowledge an already-committed duplicate with 2xx; 409 is retried like any other non-2xx
• never use webhook replay to retry a Polyflight wallet effect; reconcile the REST v1 operation by its original financial key

Dashboard workflow

1. Inspect delivery status and last response sample.
2. Fix receiver issue or secret mismatch; do not infer a wallet debit/credit from callback delivery status.
3. Replay failed or dead-letter delivery. If resending any already acknowledged 2xx callback, verify the receiver durably dedupes event_id first.
4. Confirm latest attempt becomes sent; reconcile monetary effects separately using the original financial idempotency key.