Webhooks

​

Overview

​

How It Works

​

Triggering a Delivery

curl -X POST http://localhost:8080/v1/async/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bf-vk: sk-bf-your-virtual-key" \
  -H "x-bf-async-webhook: order-events" \
  -d '{ "model": "openai/gpt-4o-mini", "messages": [...] }'

• The name must resolve to an existing, enabled endpoint. If it doesn’t, the submit request itself fails, rather than accepting the job and silently dropping the notification.
• The endpoint must still be enabled and subscribed to the resulting event (async_job.completed or async_job.failed) when the job finishes. If it isn’t, the job completes normally but no delivery is enqueued.
• Jobs submitted without the header never trigger a webhook, regardless of how many endpoints are registered.

​

The Delivery Payload

{
  "event": "async_job.completed",
  "created_at": "2026-02-19T08:10:19.412Z",
  "data": {
    "job_id": "1e89b165-d4fe-49e8-beb2-3e157f2df02f",
    "request_type": "chat_completion",
    "status": "completed",
    "status_code": 200,
    "result_url": "/v1/async/chat/completions/1e89b165-d4fe-49e8-beb2-3e157f2df02f",
    "result_expires_at": "2026-02-19T09:10:19.412Z"
  }
}

​

Verifying Deliveries

1. Recompute and compare. Recompute the HMAC from the secret and the received webhook-id, webhook-timestamp, and raw body, then compare it (in constant time) against every candidate in the webhook-signature header. Accept if any matches — the header can carry more than one signature during secret rotation.
2. Check the timestamp. Reject deliveries whose webhook-timestamp is outside a tolerance window (5 minutes is a good default) to blunt replay attacks.
3. Dedupe on webhook-id. Retries reuse the id, so process each id at most once.

​

Managing Endpoints

• Web UI
• API
• config.json

Open Webhooks in the sidebar to see your endpoints and their status.

1. Select Add Endpoint.
2. Enter a unique Name and the delivery URL (HTTPS unless the endpoint allows private networks).
3. Choose the events to subscribe to (async_job.completed, async_job.failed).
4. Optionally add custom headers (for example an Authorization value your receiver requires) and toggle Include response to inline job responses.

5. Save. The signing secret is shown once in a dialog — copy it now; you cannot retrieve it again.

6. Open an endpoint to see its recent deliveries, send a Test delivery, or Rotate secret if a secret is ever exposed. Rotation takes effect immediately with no grace window, so update your receiver in the same change.

7. For anything beyond the last few deliveries, use View delivery history to open the dedicated deliveries page at /workspace/webhooks/deliveries. It lists deliveries across every endpoint and filters by outcome, event, response status class (2xx/4xx/5xx/no response), webhook, and time range, with lookup by request ID or delivery ID. Arriving from an endpoint pre-selects that webhook; clear the filter to see deliveries fleet-wide.

Rows are grouped by delivery, not by attempt: one row is one notification owed to the endpoint, and its 503 → 503 → 200 chips are that delivery’s attempts. A delivery that was manually redelivered expands to show each send separately.

Create an endpoint. The signing secret is server-generated and returned once in the create response — it is never accepted as input.

curl -X POST http://localhost:8080/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order-events",
    "url": "https://example.com/webhook",
    "events": ["async_job.completed", "async_job.failed"],
    "include_response": false
  }'

Other operations:

Method	Path	Purpose
GET	/api/webhooks	List endpoints (supports search, event, and status filters).
POST	/api/webhooks	Create an endpoint; returns the signing secret once.
GET	/api/webhooks/{id}	Get one endpoint.
PUT	/api/webhooks/{id}	Update an endpoint. The secret is immutable here.
DELETE	/api/webhooks/{id}	Delete an endpoint.
POST	/api/webhooks/{id}/rotate-secret	Rotate the signing secret; returns the new secret once.
POST	/api/webhooks/{id}/test	Send a test delivery for a chosen event.
GET	/api/webhooks/{id}/deliveries	List delivery history for the endpoint.
GET	/api/webhooks/deliveries	Search delivery history across endpoints, with filters.
POST	/api/webhooks/deliveries/{id}/redeliver	Re-queue a past delivery.

The secret is never returned again after creation or rotation, and cannot be set or changed through the create/update body. Rotating is the only way to change it.

Declare endpoints under the top-level webhooks array. They are synced into the database at startup and reconciled by name.

{
  "webhooks": [
    {
      "name": "order-events",
      "url": "https://example.com/webhook",
      "events": ["async_job.completed", "async_job.failed"],
      "secret": "env.WEBHOOK_SIGNING_SECRET",
      "include_response": false
    }
  ]
}

Field	Type	Required	Description
name	string	Yes	Unique endpoint name; the reconcile key.
url	string	Yes	Delivery URL. HTTPS required unless allow_private_network is set.
events	array	Yes	Subscribed events: async_job.completed, async_job.failed.
secret	string	No	Signing secret in whsec_ format. Best supplied as an env reference (env.MY_VAR); generated when omitted.
headers	object	No	Custom headers sent with every delivery. Values support env.VAR syntax and are encrypted at rest when encryption_key is configured. Reserved delivery headers cannot be overridden.
include_response	boolean	No	Inline the job response into payloads (default false).
allow_private_network	boolean	No	Permit private-network receivers and plain http (default false).
disabled	boolean	No	Register the endpoint without delivering to it (default false).

config.json is the only place you can supply your own signing secret, and an env. reference is the recommended form. Prefer creating endpoints through the UI or API so the secret is generated for you.

The global retention setting lives under client:

{
  "client": {
    "webhook_config": {
      "delivery_history_retention_days": 30
    }
  }
}

​

Tuning Deliveries

​

Next Steps

• Async Inference — submit jobs and poll for results; webhooks notify you when those jobs finish.
• Virtual Keys — the x-bf-vk keys used to submit async jobs and fetch results.
• Storage: Logs Store — configure the Logs Store that both Async Inference and Webhooks require.