Webhooks

​

Overview

​

How It Works

​

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 view its delivery history, 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.

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.
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.
• Keys Management — manage the virtual keys used to submit async jobs and fetch results.