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
• empty enabled_events means subscribe to all current event types
• max_attempts defaults to 6 and is capped at 10
• timeout_seconds defaults to 5 and is capped at 30

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.

Replaying a successful 200 delivery sends the same callback object again and must be safe because your receiver dedupes by event_id.

Delete flow

Dashboard uses:

POST /api/operator/webhooks/endpoints/{id}/delete

This is a compatibility fallback for environments where dynamic DELETE routes are unreliable. The REST DELETE /api/operator/webhooks/endpoints/{id} route also exists.

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
• delivery dashboard: /docs/dashboard/webhook-deliveries
• retry semantics: /docs/webhooks/retry-and-replay