A valid request URL is required to generate request examples{
"endpoint": {
"id": "<string>",
"name": "<string>",
"url": "<string>",
"events": [
"async_job.completed"
],
"headers": {},
"include_response": true,
"allow_private_network": true,
"disabled": true,
"max_retries": 123,
"retry_backoff_initial_seconds": 123,
"retry_backoff_max_seconds": 123,
"attempt_timeout_seconds": 123,
"max_response_payload_kbs": 123,
"max_concurrent_deliveries": 123,
"consecutive_failures": 123,
"last_success_at": "2023-11-07T05:31:56Z",
"last_failure_at": "2023-11-07T05:31:56Z",
"config_hash": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
},
"secret": "<string>"
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}Create a webhook endpoint
Creates a webhook endpoint. The signing secret is generated by the server and returned once in the response — it cannot be supplied and cannot be retrieved again afterwards.
A valid request URL is required to generate request examples{
"endpoint": {
"id": "<string>",
"name": "<string>",
"url": "<string>",
"events": [
"async_job.completed"
],
"headers": {},
"include_response": true,
"allow_private_network": true,
"disabled": true,
"max_retries": 123,
"retry_backoff_initial_seconds": 123,
"retry_backoff_max_seconds": 123,
"attempt_timeout_seconds": 123,
"max_response_payload_kbs": 123,
"max_concurrent_deliveries": 123,
"consecutive_failures": 123,
"last_success_at": "2023-11-07T05:31:56Z",
"last_failure_at": "2023-11-07T05:31:56Z",
"config_hash": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
},
"secret": "<string>"
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}{
"event_id": "<string>",
"type": "<string>",
"is_bifrost_error": true,
"status_code": 123,
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"param": "<string>",
"event_id": "<string>"
},
"extra_fields": {
"provider": "anthropic",
"model_requested": "<string>",
"request_type": "<string>",
"error_type": "<string>",
"retry_after_ms": 150500
}
}| Permission | Granted via |
|---|---|
Webhooks:Create | RBAC role or API key scope |
Authorizations
Management API authentication for /api/* endpoints. Use the Authorization header
with Bearer <token>, where <token> is one of:
- a Bifrost management API key,
- a dashboard session token issued by
POST /api/session/login, - base64 of
<admin-username>:<admin-password>(legacy equivalent ofBasicAuth).
Virtual keys (sk-bf-*) and the x-api-key header are not accepted on management APIs -
the sole exception is GET /api/governance/virtual-keys/quota, which is virtual-key-only.
Authentication alone is not sufficient in Bifrost Enterprise: each operation page shows a
Required Permissions table (Resource:Operation, for example Dashboard:View) above
its Authorizations section, and the caller's RBAC role or management API key scopes must
include what it lists, otherwise the request is rejected with 403 Forbidden.
A local admin — authenticated with the admin password, or any caller on a deployment with dashboard auth disabled — bypasses these checks and can call every management endpoint.
OSS setup lock. On Bifrost OSS, while dashboard auth is not active (no admin account,
or auth disabled), every management endpoint except the public ones (/health,
/api/version, /api/session/is-auth-enabled, /api/session/login, ...) requires the
operator's setup token in the X-Bifrost-Setup-Token header, in place of Authorization.
The token is set with setup_token in config.json or the BIFROST_SETUP_TOKEN
environment variable. A missing header returns 401, a wrong token 403. The header
stops working once dashboard auth is enabled. The dashboard instead trades the token once
for an HttpOnly bifrost_setup_session cookie via POST /api/session/setup.
See Required permissions for how
permissions are derived and which endpoints are exempt.
Body
Create or update body for a webhook endpoint. The signing secret is never accepted here — it is generated by the server and returned once at creation, and can only be changed through the rotate-secret endpoint.
Unique endpoint name.
Delivery URL. HTTPS is required unless allow_private_network is set.
Events this endpoint subscribes to.
A terminal async-job event a webhook endpoint can subscribe to:
- async_job.completed: an async job finished successfully
- async_job.failed: an async job finished with an error
async_job.completed, async_job.failed Custom headers sent with every delivery. Values support env var syntax ("env.MY_VAR") and are encrypted at rest. Reserved delivery headers (webhook-id, webhook-timestamp, webhook-signature, content-type, etc.) cannot be overridden.
Show child attributes
Show child attributes
Inline the job response into delivery payloads, capped by max_response_payload_kbs.
Permit private-network receivers and plain http. Link-local and metadata addresses stay blocked.
Register the endpoint without delivering to it.
Retries after the first failed attempt (default 4). 0 selects the default.
x >= 0Delay before the first retry; each further retry doubles it (default 30). 0 selects the default.
x >= 0Cap on the per-retry delay (default 1800). 0 selects the default.
x >= 0End-to-end bound for one delivery attempt (default 10). 0 selects the default.
x >= 0Cap for inlined response payloads in KB when include_response is set (default 256). 0 selects the default.
x >= 0Concurrent in-flight deliveries to this endpoint per node (default 10). 0 selects the default.
x >= 0Response
Endpoint created; signing secret returned once.
Returned once when an endpoint is created or its secret is rotated. The secret is shown a single time and cannot be retrieved again.
Was this page helpful?