Webhooks

Webhooks push control-plane and inference events to an HTTPS endpoint you operate. Eridian delivers at-least-once with exponential backoff for 24 hours. Verify every payload as documented in Webhook Signing.

Create

POST /v1/webhooks
Authorization: Bearer eridian_sk_...
Content-Type: application/json
Idempotency-Key: wh-legal-siem-001

{
  "project_id": "prj_legal_001",
  "url": "https://siem.example.bank/webhooks/eridian",
  "events": [
    "inference.completed",
    "budget.threshold",
    "budget.exceeded",
    "key.rotated",
    "policy.updated",
    "approval.approved"
  ]
}

{
  "id": "wh_02c9",
  "object": "eridian.webhook",
  "status": "active",
  "secret": "whsec_...",
  "events": ["inference.completed", "budget.threshold"]
}

secret is returned once. Required scope: governance:manage. Endpoints must use HTTPS. Private networks are supported on Enterprise via allowlisted egress.

Event Envelope

POST /webhooks/eridian HTTP/1.1
Content-Type: application/json
X-Eridian-Signature: t=1718400000,v1=...
X-Eridian-Event: inference.completed
X-Eridian-Delivery-Id: del_91aa
X-Eridian-Webhook-Id: wh_02c9

{
  "id": "evt_55ab",
  "object": "eridian.webhook.event",
  "type": "inference.completed",
  "created_at": 1718400000,
  "project_id": "prj_legal_001",
  "data": {
    "request_id": "axm_req_8f3a2b1c",
    "route": "gpt",
    "cache_hit": false,
    "cost_usd": 0.0042,
    "region": "eu-west-1"
  }
}

Return HTTP 2xx within 10 seconds. Any other status is a failure.

Delivery and Retries

Disable a webhook with POST /v1/webhooks/wh_02c9/disable to stop retries.

List Deliveries

GET /v1/webhooks/wh_02c9/deliveries?starting_after=del_91aa
Authorization: Bearer eridian_sk_...

Replay a failed delivery:

POST /v1/webhooks/wh_02c9/deliveries/del_91aa/replay

Event Catalog

Vertical event catalogs: Ops Webhooks, Pull Requests. Subscribe only to events you will handle. Unused events still count against delivery rate limits.

See Webhook Signing and Budgets.