Webhook endpoints

Manage webhook endpoints for authenticated operator.

Paths

• GET /api/operator/webhooks/endpoints
• GET /api/operator/webhooks/endpoints/history
• POST /api/operator/webhooks/endpoints
• PATCH /api/operator/webhooks/endpoints/{id}
• DELETE /api/operator/webhooks/endpoints/{id}
• POST /api/operator/webhooks/endpoints/{id}/delete

Required scopes and path parameters

Create body

{
  "url": "https://operator.example/webhooks/openpoly",
  "secret": "whsec_...",
  "enabled_events": [
    "mini_app.trade.processed",
    "mini_app.polyflight.purchase.processed",
    "mini_app.polyflight.payout.processed"
  ],
  "max_attempts": 6,
  "timeout_seconds": 5
}

Patch body

Every patch field is optional. Omitted values keep the current setting.

Use the endpoint's returned enabled_events as the starting selection in an editor, including any selections not shown by an older UI. Omit enabled_events when changing only URL or secret. A blank replacement secret keeps the current signing secret. An empty list means all current and future allowed event types, not no events; prefer an explicit set if new types require review.

Rules

• HTTPS required except localhost or 127.0.0.1
• empty enabled_events subscribes endpoint 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
• invalid events -> 400 INVALID_ENABLED_EVENTS
• patch status must be active or disabled
• response exposes has_secret, never raw secret
• delete returns { "id": number, "deleted": true }
• GET returns event_catalogue grouped as opinion and polyflight, plus items; use it to build selectors instead of hardcoding one product's list

Subscriptions can combine Opinion and Polyflight events. All ten Opinion plus eight Polyflight names are in the catalogue; the operator's Polyflight delivery-monitor read access is separately gated by polyflight:read. Updating an existing endpoint need not re-register it or disrupt deliveries to its original URL.

Response fields

• id
• url
• status
• enabled_events
• max_attempts
• timeout_seconds
• has_secret
• created_at
• updated_at

Each endpoint item has the fields above. The GET envelope also includes event_catalogue.opinion and event_catalogue.polyflight. The Polyflight group contains the eight events in Event types.

Saved setup history

GET /api/operator/webhooks/endpoints/history?page=1&page_size=10 returns { items, pagination }, newest recording time first with ID as tie-breaker. It uses standard pagination and includes deleted endpoints belonging to the authenticated operator.

Each item has id, endpoint_id, action (baseline, created, updated, deleted), actor (type, nullable id, label), nullable before/after snapshots, boolean secret_changed, and UTC created_at.

Snapshots contain url, status, enabled_events, max_attempts, timeout_seconds, has_secret, created_at, and updated_at. No raw/encrypted secret or hash is returned. Actors come from the authenticated staff account or API key, not request JSON; an API-key label identifies the credential, not a presumed human. Successful writes and their audit entries commit atomically.

A baseline is capture-time evidence with an unknown prior actor, not a reconstructed creation/change event. Its record timestamp is capture time; the endpoint timestamps inside its snapshot are separate. secret_changed=false on creation/baseline does not establish whether an older secret was rotated.

Deletion retains setup history but removes the endpoint's delivery history. Setup history cannot recreate missing HTTP attempts. Prefer disabling an endpoint while investigating if delivery evidence must remain available. See Setup history for the full response shape and provenance limits.