<!-- Markdown twin of https://pixelvault.dev/docs/webhooks/ -->

# 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](/dashboard/settings/webhooks/), the API, the [CLI](/docs/cli/#webhooks), or [MCP](/docs/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](/docs/api/webhooks/#create_webhook), [list](/docs/api/webhooks/#list_webhooks), [update](/docs/api/webhooks/#update_webhook), [delete](/docs/api/webhooks/#delete_webhook), [rotate secret](/docs/api/webhooks/#rotate_webhook_secret), [deliveries](/docs/api/webhooks/#list_webhook_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](/docs/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`:

Verify

Node.jsPython

```
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`](/examples/video-enrichment-webhook.mjs) and [`audio-enrichment-webhook.mjs`](/examples/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](/docs/async-jobs/): the polling fallback.
-   [Video transcripts](/docs/guides/video-transcripts/) with a webhook pipeline.
-   [Webhook endpoints in the API reference](/docs/api/webhooks/#create_webhook).
