Images Videos Audio Pricing Docs View as Markdown (Agent) Get started
Human Agent

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

TypeSent when
media.createdAn image, video or audio asset was created. source is upload, url_import, claim, generation, or edit.
media.deletedAn asset was deleted through a delete endpoint. Carries no URLs. Expiry sweeps don't emit it.
image.description.completedAn AI description finished; carries alt text, caption, OCR text and tags.
image.description.failedAn AI description failed.
export.completedAn export archive is ready; carries status_url and download_url.
export.failedAn export failed.
video.optimization.completedA social-ready copy is ready.
video.optimization.failedA social-ready copy failed.
video.enrichment.completedVideo transcript and storyboard artifacts are ready.
video.enrichment.failedVideo enrichment failed.
audio.enrichment.completedAn audio transcript is ready.
audio.enrichment.failedAudio 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:

HeaderValue
X-PixelVault-Webhook-IdThe event id (whe_…), the same on every retry
X-PixelVault-Webhook-EventThe event type
X-PixelVault-Webhook-TimestampUnix time in seconds when this attempt was signed
X-PixelVault-Webhook-Signaturev1,<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
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