Webhooks
Starter and Pro projects can receive signed callbacks for consumer-actionable media lifecycle events, instead of polling. Configure up to 3 endpoints on Starter or 10 on Pro from Dashboard → Settings → Webhooks, the API, the CLI, or MCP. On the free plan, creating an endpoint returns 402 webhooks_require_paid_plan.
Create an endpoint
curl -X POST https://api.pixelvault.dev/v1/webhooks \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/pixelvault-events",
"description": "media transcript pipeline",
"events": ["video.enrichment.completed", "video.enrichment.failed",
"audio.enrichment.completed", "audio.enrichment.failed"]
}'
# → 201; data.signing_secret ("whsec_…") is returned ONCE Endpoint URLs must be public HTTPS on port 443, at most 2,048 characters, without credentials. Omit events to subscribe to every type. A duplicate URL is 409 webhook_url_exists; going past the plan's cap is 409 webhook_limit_reached. Store the signing_secret now: it is shown once. Manage endpoints with:
GET /v1/webhooks
PATCH /v1/webhooks/:id # url, description, events, active
DELETE /v1/webhooks/:id
POST /v1/webhooks/:id/rotate-secret
GET /v1/webhooks/:id/deliveries # newest first; retained 30 days Reference: create, list, update, delete, rotate secret, deliveries. Rotating replaces the secret immediately; deploy the new one right away.
Events
| Type | Sent when |
|---|---|
media.created | An image, video or audio asset was created. source is upload, url_import, claim, generation, or edit. |
media.deleted | An asset was deleted through a delete endpoint. Carries no URLs. Expiry sweeps don't emit it. |
image.description.completed | An AI description finished; carries alt text, caption, OCR text and tags. |
image.description.failed | An AI description failed. |
export.completed | An export archive is ready; carries status_url and download_url. |
export.failed | An export failed. |
video.optimization.completed | A social-ready copy is ready. |
video.optimization.failed | A social-ready copy failed. |
video.enrichment.completed | Video transcript and storyboard artifacts are ready. |
video.enrichment.failed | Video enrichment failed. |
audio.enrichment.completed | An audio transcript is ready. |
audio.enrichment.failed | Audio transcription failed. |
Generation and editing are synchronous, so their failures stay in the API response instead of producing a second webhook; successful outputs emit media.created.
Payload
Every delivery is a JSON POST with the envelope id, type, created_at, data:
{
"id": "whe_…",
"type": "video.enrichment.completed",
"created_at": "2026-11-16T12:00:00.000Z",
"data": {
"video": { "id": "vid_…", "kind": "video", "original_url": "https://…",
"visibility": "private", "signed_expires": 1795449600 },
"enrichment": {
"job_id": "ven_…", "status": "complete",
"status_url": "https://api.pixelvault.dev/v1/videos/vid_…",
"refresh_url": "https://api.pixelvault.dev/v1/videos/vid_…/sign-url",
"signed_expires": 1795449600,
"artifacts": [
{ "type": "transcript_vtt", "content_type": "text/vtt; charset=utf-8", "url": "https://…" },
{ "type": "storyboard_index", "content_type": "application/json; charset=utf-8", "url": "https://…" }
]
}
}
} Completed events contain only artifacts that exist. Audio events contain the stable aud_ asset and aen_ job IDs, safe terminal outcome, and transcript references; they never invent a storyboard. Private original and artifact URLs are temporary bearer links with one signed_expires; the event never contains credentials or permanent public fallbacks. When they expire, authenticate and POST the payload's refresh_url with {"expires_in":3600}. Failed events contain a safe code/message and no artifact URLs. Clients without a callback endpoint can keep polling GET /v1/videos/:id or GET /v1/audio/:id (see Async jobs).
Verify signatures
Each delivery carries four headers:
| Header | Value |
|---|---|
X-PixelVault-Webhook-Id | The event id (whe_…), the same on every retry |
X-PixelVault-Webhook-Event | The event type |
X-PixelVault-Webhook-Timestamp | Unix time in seconds when this attempt was signed |
X-PixelVault-Webhook-Signature | v1,<base64url HMAC-SHA256>, unpadded |
The signature is an HMAC-SHA256 over <event-id>.<timestamp>.<raw-request-body>, keyed with the endpoint's full whsec_… secret. Verify the raw body before parsing JSON, reject stale timestamps, compare signatures in constant time, and deduplicate on the event id:
import { createHmac, timingSafeEqual } from "node:crypto";
// rawBody: the request body as a Buffer, BEFORE JSON parsing.
export function verifyPixelVault(headers, rawBody, secret = process.env.PIXELVAULT_WEBHOOK_SECRET) {
const id = headers["x-pixelvault-webhook-id"];
const timestamp = headers["x-pixelvault-webhook-timestamp"];
const signature = headers["x-pixelvault-webhook-signature"];
if (!id || !timestamp || !signature) return false;
// Reject stale or future timestamps (seconds) to block replays.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const digest = createHmac("sha256", secret) // the full "whsec_…" string is the key
.update(`${id}.${timestamp}.`)
.update(rawBody)
.digest("base64url");
const expected = Buffer.from(`v1,${digest}`);
const received = Buffer.from(signature);
return expected.length === received.length && timingSafeEqual(expected, received);
} Runnable Node 20 callbacks: video-enrichment-webhook.mjs and audio-enrichment-webhook.mjs. Set PIXELVAULT_WEBHOOK_SECRET=whsec_…, run the example, and expose /pixelvault-events through public HTTPS. Each verifies the raw-body signature and timestamp before parsing, acknowledges duplicate event IDs, and avoids logging private artifact URLs. Replace its in-memory dedupe set with durable storage before running multiple instances.
Delivery and retries
Respond with any 2xx within 10 seconds. Any other status (including a 3xx: redirects are not followed), a timeout, or a network failure is retried after approximately 1 minute, 5 minutes, 30 minutes, and 2 hours, for 5 attempts in total. Delivery is at least once: retries keep the same event ID, so make your handler idempotent. A failed enrichment retried through the API is a later attempt with a new job_id and event ID.
The delivery log (GET /v1/webhooks/:id/deliveries) stores status (pending, delivering, retrying, delivered, failed, skipped for a disabled endpoint), attempts, response code, and a bounded error message for 30 days; response bodies and signing secrets are never stored.
Next steps
- Async jobs: the polling fallback.
- Video transcripts with a webhook pipeline.
- Webhook endpoints in the API reference.