Operator Api

Webhook endpoints

Configure webhook endpoint records through the operator API.

Webhook endpoints

Manage webhook endpoints for authenticated operator.

Paths

GET /api/operator/webhooks/endpoints
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

Endpoint	Required scope	Required path parameter
`GET /api/operator/webhooks/endpoints`	`webhooks:read`	None.
`POST /api/operator/webhooks/endpoints`	`webhooks:write`	None.
`PATCH /api/operator/webhooks/endpoints/{id}`	`webhooks:write`	`id`: positive endpoint ID.
Both delete variants	`webhooks:write`	`id`: positive endpoint ID.

Create body

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

Field	Type	Requirement	Values/default
`url`	string	Required	HTTPS URL. HTTP is accepted only for `localhost` and `127.0.0.1`.
`secret`	string	Required	Non-empty signing secret; stored encrypted and never returned.
`enabled_events`	string	Optional	Default `[]`, which subscribes to all current event types.
`max_attempts`	positive integer	Optional	Default `6`, maximum `10`. Invalid/non-positive input falls back to `6`.
`timeout_seconds`	positive integer	Optional	Default `5`, maximum `30`. Invalid/non-positive input falls back to `5`.

Patch body

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

Field	Type	Requirement	Notes
`url`	string	Optional	Same validation as create.
`secret`	string	Optional	Non-empty value replaces the stored secret.
`enabled_events`	string or `null`	Optional	`[]` or `null` subscribes to all current events.
`max_attempts`	positive integer	Optional	Maximum `10`; invalid/non-positive input keeps the current value.
`timeout_seconds`	positive integer	Optional	Maximum `30`; invalid/non-positive input keeps the current value.
`status`	string	Optional	`active` or `disabled`.

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 }

Response fields

id
url
status
enabled_events
max_attempts
timeout_seconds
has_secret
created_at
updated_at

Edit this pageorReport an issue

Authentication

Authenticate requests to the operator API.

Webhook deliveries

Inspect and replay webhook deliveries.