Webhook endpoints

Dashboard webhook settings control where OpenPoly sends callback events.

Configure endpoint

For each endpoint record define:

• destination URL
• subscribed events
• shared secret
• max attempts
• timeout seconds

Rules:

• HTTPS required except allowed localhost testing cases
• secret never shown back in API response
• disabled endpoint receives no new deliveries

Event subscription strategy

Start with minimum set needed by operator systems.

Common starting set:

• mini_app.trade.processed
• mini_app.trade.failed
• mini_app.redemption.processed
• mini_app.redemption.failed
• mini_app.payout.pending

Full list: /docs/webhooks/event-types

Replay workflow

1. inspect failed or dead-letter delivery
2. fix receiver issue or secret mismatch
3. replay delivery from dashboard
4. confirm latest attempt becomes sent

Replay does not create new business event.

Disable flow

Disable endpoint when:

• receiver under maintenance
• secret suspected leaked
• endpoint moved to new path

Re-enable only after smoke test on fixed receiver.

Troubleshooting cues

• repeated 401 -> secret mismatch or bad raw-body handling
• repeated 500 -> receiver app failing after verification
• dead_letter -> retries exhausted, operator action required

Related pages

• operator API contract: /docs/operator-api/webhook-endpoints
• delivery inspection: /docs/operator-api/webhook-deliveries
• retry semantics: /docs/webhooks/retry-and-replay