Docs / Platform

Webhooks

Subscribe an HTTPS endpoint to domain events. Each delivery is HMAC-signed, retried with backoff, and dead-lettered after six attempts — so you can drive downstream pipelines off the platform's own lifecycle.

Manage subscriptions

POST /v1/webhooks webhooks:write

Subscribe an endpoint to events. The URL is SSRF-vetted. Returns the signing secret once — store it to verify deliveries.

curl

curl -X POST https://api.ollanode.com/v1/webhooks \
  -H "Authorization: Bearer $OLLANODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/olla","events":["video.asset.ready","video.asset.errored"]}'

Response

{ "id":"wh_...", "url":"https://hooks.example.com/olla",
  "events":["video.asset.ready","video.asset.errored"],
  "active":true, "secret":"<shown once>" }

GET /v1/webhooks webhooks:read

List webhooks (no secret).

PATCH /v1/webhooks/{id} webhooks:write

Update url, events, or active.

DELETE /v1/webhooks/{id} webhooks:write

Remove a webhook.

GET /v1/webhooks/{id}/deliveries webhooks:read

Recent delivery attempts (newest first) with status and response code.

Events

The public event vocabulary (Mux-compatible naming). Subscribe to specific names, or "*" for all.

Event	Fires when
`video.asset.created`	A video record is created
`video.asset.processing`	The pipeline starts
`video.asset.transcoded`	The ladder is encoded
`video.asset.ready`	The video is playable
`video.asset.errored`	Processing failed
`video.asset.thumbnail.ready`	Thumbnails/storyboard are ready
`video.asset.track.ready`	A transcript/subtitle track is ready
`function.error_spike`	An edge function's error rate spikes

Delivery payload & signature

Every delivery carries X-VB-Signature: sha256=… (HMAC-SHA256 of the raw body with your webhook secret), plus X-VB-Event and X-VB-Delivery-Id.

delivery

POST https://hooks.example.com/olla
X-VB-Signature: sha256=<HMAC-SHA256(secret, raw_body)>
X-VB-Event: video.asset.ready
X-VB-Delivery-Id: <id>

{ "id":"<uuid>", "type":"video.asset.ready", "api_version":"2026-06-01",
  "created_at":"...", "project_id":"proj_...", "video_id":"vid_...", "data":{ } }

verify (Node.js)

import crypto from "node:crypto";
function verify(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

Retries & dead-letter

Failed deliveries retry with backoff at 10s, 30s, 2m, 10m, 30m, 2h — up to 6 attempts, after which the delivery is dead_lettered. Statuses: pending, delivering, delivered, failed, dead_lettered. Fan-out is deduped per (event_id, webhook_id).

Use cases: kick a publishing pipeline when video.asset.ready fires; page on-call when function.error_spike fires.