Webhook endpoints

Dashboard webhook settings control where OpenPoly sends callback events.

Open Integrations → Callback Settings (/settings/callbacks). Reading endpoints, setup history and recent deliveries requires webhooks:read; creating/editing, enable/disable, delete and replay additionally require webhooks:write. Polyflight delivery rows require polyflight:read, separately from subscription editing.

Configure endpoint

For each endpoint record define:

• destination URL
• subscribed events
• shared secret

The API additionally supports per-endpoint max_attempts and timeout_seconds. The current dashboard editor changes URL, events, and secret; use the API or API Playground to change retry/timeout policy.

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

The dashboard editor starts from the endpoint's saved URL and exact event selection; it does not replace a saved secret unless a new secret is entered. Choose from all ten Opinion and eight Polyflight names. Existing selections remain intact when editing other fields. A new dashboard endpoint initially selects the ten Opinion events; select Polyflight explicitly when needed. Clearing the selection saves [], meaning all current and future allowed events, not “none”.

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.trade.compensation_required

For Polyflight, select mini_app.polyflight.purchase.processed, mini_app.polyflight.purchase.failed, and the relevant ticket, payout, refund, and compensation events. Pending payout/refund means money owed, not money credited. The fee on a purchase is part of the stake debit; a cancelled ticket is refunded the full stake.

Full list: /docs/webhooks/event-types

Allowlisted lifecycle names and mini_app.payout.pending do not imply the current processor emits each name. Opinion unresolved redemption payouts currently emit mini_app.redemption.failed with status = manual_review; see the event reference before depending on an event.

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 2xx delivery sends the same callback event again and must be safe because your receiver durably dedupes by event_id.

The Recent Deliveries tab uses retained-delivery replay. Open Full delivery monitor for queued single/bulk Resend or event-only historical backfill. The full monitor distinguishes real attempts from terminal skips and unavailable history. Creating/enabling an endpoint never automatically backfills old callbacks. Retained replay uses the same endpoint record's current URL and secret, so review Setup History after changes.

Setup History

The Setup History tab lists changes newest first, including deleted endpoints. Expand Settings to compare URL, status, exact event selection, retry/timeout policy, secret-presence flag and endpoint timestamps. Entries record authenticated staff or API-key identity; a key identifies a credential, not a guessed person.

baseline entries capture settings when auditing began, with unknown prior actor. Their recording time is not original creation time, and no pre-baseline change history is invented. secret_changed exposes only a boolean; secret values and hashes are never shown. See setup history provenance.

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.

The confirmation warns that deletion removes delivery history but retains setup history. Missing delivery history later appears as unknown, not proof no callback was sent. Disable rather than delete while preserving evidence for an incident.

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