Overview

OpenPoly webhooks notify operator backend after business state already committed.

Delivery model

1. OpenPoly business flow commits DB state.
2. OpenPoly writes outbox event.
3. Dispatcher creates per-endpoint delivery records.
4. Dispatcher signs raw JSON payload and sends POST request.
5. Operator receiver verifies signature, deduplicates event_id, then processes event.

Webhook send is not part of wallet mutation or trade DB transaction.

Important guarantees

• business state does not roll back if webhook delivery fails
• same outbox event can produce multiple delivery attempts
• replay creates another delivery attempt for same event
• disabled endpoint receives no new deliveries
• dead-letter delivery stays visible for operator review and replay

What receiver must do

• read raw request body
• verify X-Polynion-Signature
• reject stale timestamp
• dedupe by event_id
• return 2xx only after durable processing

State model

Outbox event statuses:

• pending
• dispatching
• dispatched
• failed
• dead_letter

Delivery statuses:

• pending
• sent
• failed
• dead_letter

Delivery boundaries

• 2xx -> delivery marked sent
• 410 -> delivery marked dead_letter immediately
• other non-2xx -> retry until max attempts, then dead_letter
• timeout/network/DNS/TLS failure -> retry until max attempts, then dead_letter

Where operators configure webhooks

• create and update endpoints: /docs/operator-api/webhook-endpoints
• inspect deliveries and replay: /docs/operator-api/webhook-deliveries
• verify signatures: /docs/webhooks/signatures