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

API reference

Webhooks

Starter and Pro projects receive signed HTTPS callbacks for media lifecycle events (up to 3 endpoints on Starter, 10 on Pro). Manage endpoints, rotate signing secrets and read the delivery log.

The Webhook endpoint object

An HTTPS destination that receives signed event deliveries for the project.

Properties

The Webhook endpoint object properties
Property Type Description
id string

Endpoint id (whk_ prefix).

url string (uri)

Public HTTPS URL on the default port (443), at most 2048 characters, no credentials. Redirects are never followed.

description string nullable

Free-text label, at most 100 characters.

events array of string

Event types delivered to this endpoint.

One of: media.created, media.deleted, image.description.completed, image.description.failed, export.completed, export.failed, video.optimization.completed, video.optimization.failed, video.enrichment.completed, video.enrichment.failed, audio.enrichment.completed, audio.enrichment.failed

active boolean

Inactive endpoints keep their configuration but receive nothing; queued deliveries are marked skipped.

created_at string (date-time)
updated_at string (date-time)
The Webhook endpoint object
{
  "id": "whk_abc123",
  "url": "https://api.example.com/pixelvault-events",
  "description": "media pipeline",
  "events": [
    "media.created",
    "media.deleted",
    "export.completed",
    "export.failed"
  ],
  "active": true,
  "created_at": "2026-11-16T12:00:00.000Z",
  "updated_at": "2026-11-16T12:00:00.000Z"
}

List webhook endpoints

GET /v1/webhooks

The current project's webhook endpoints (oldest first), the plan's endpoint limit, and the event types you can subscribe to. Requires a secret API key or dashboard session.

Authentication

API key, or a dashboard session token, sent as Authorization: Bearer <token>.

Responses

  • 200

    Webhook endpoints and entitlement

  • 401

    unauthorized: no Bearer token, or the dashboard session is invalid or expired. invalid_api_key: the API key is unknown or revoked.

  • 403

    webhook_management_forbidden: publishable keys cannot manage webhooks. account_suspended: the account is suspended.

  • 404

    no_project: the signed-in account has no project.

  • 429

    rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour Retry-After.

Request
curl https://api.pixelvault.dev/v1/webhooks \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
Response 200
{
  "data": {
    "webhooks": [
      {
        "id": "whk_abc123",
        "url": "https://api.example.com/pixelvault-events",
        "description": "media pipeline",
        "events": [
          "media.created",
          "media.deleted",
          "export.completed",
          "export.failed"
        ],
        "active": true,
        "created_at": "2026-11-16T12:00:00.000Z",
        "updated_at": "2026-11-16T12:00:00.000Z"
      }
    ],
    "limit": 3,
    "remaining": 2,
    "available_events": [
      "media.created",
      "media.deleted",
      "image.description.completed",
      "image.description.failed",
      "export.completed",
      "export.failed",
      "video.optimization.completed",
      "video.optimization.failed",
      "video.enrichment.completed",
      "video.enrichment.failed",
      "audio.enrichment.completed",
      "audio.enrichment.failed"
    ]
  }
}

Create a webhook endpoint

POST /v1/webhooks

Create a public-HTTPS endpoint that receives signed callbacks for consumer-actionable media lifecycle events. Starter supports 3 endpoints and Pro 10; Free receives 402. The signing_secret (whsec_…) is returned once; rotate it with rotate_webhook_secret. Also configurable from Dashboard → Settings → Webhooks, the CLI (pixelvault webhooks create https://…) and MCP.

Events (default: all):

  • media.created: an image, PDF, video or audio asset was stored; data.source is upload, url_import, claim, generation or edit
  • media.deleted: identifies the deleted asset (with reason and deleted_at) but deliberately omits its now-dead URL
  • image.description.completed / image.description.failed
  • export.completed / export.failed: carries the export's status_url and, when complete, download_url
  • video.optimization.completed / video.optimization.failed
  • video.enrichment.completed / video.enrichment.failed
  • audio.enrichment.completed / audio.enrichment.failed

Generation and editing are synchronous, so their failures stay in the API response instead of producing a webhook; successful outputs emit media.created.

Delivery: each delivery is a JSON POST of { id, type, created_at, data } with the headers X-PixelVault-Webhook-Id, X-PixelVault-Webhook-Event, X-PixelVault-Webhook-Timestamp and X-PixelVault-Webhook-Signature. The signature is v1,<base64url HMAC-SHA256> over <event-id>.<timestamp>.<raw-request-body> using the endpoint's secret. Verify the raw body before parsing JSON, reject stale timestamps, compare signatures in constant time, and deduplicate on the event id.

Delivery is at least once: retries keep the same event id. Any 2xx acknowledges. Non-2xx responses, timeouts (10 seconds) and network failures retry after about 1 minute, 5 minutes, 30 minutes and 2 hours (5 attempts in total). Redirects are not followed. Inspect attempts with list_webhook_deliveries.

Video and audio enrichment events carry stable asset and job ids, a safe outcome and only artifacts that exist; a failed job retried through the API is a new attempt with a new job_id and event id. Private original and artifact URLs in payloads are temporary bearer links sharing signed_expires; when they expire, authenticate and POST the payload's refresh_url with {"expires_in":3600}. Payloads never contain credentials. Polling get_video and get_audio remains supported. Runnable Node 20 verifiers: video-enrichment-webhook.mjs and audio-enrichment-webhook.mjs.

Authentication

API key, or a dashboard session token, sent as Authorization: Bearer <token>.

Request body

application/json, required

Request body
Name Type Required Description
url string (uri) Required

Public HTTPS URL on the default port (443), without credentials. Redirects are not followed. One endpoint per URL per project.

max length 2048

description string nullable Optional

Free-text label.

max length 100

events array of string Optional

Event types to deliver. Omit for all.

One of: media.created, media.deleted, image.description.completed, image.description.failed, export.completed, export.failed, video.optimization.completed, video.optimization.failed, video.enrichment.completed, video.enrichment.failed, audio.enrichment.completed, audio.enrichment.failed

Default: ["media.created","media.deleted","image.description.completed","image.description.failed","export.completed","export.failed","video.optimization.completed","video.optimization.failed","video.enrichment.completed","video.enrichment.failed","audio.enrichment.completed","audio.enrichment.failed"]

min items 1

Responses

  • 201

    Endpoint created; signing_secret is shown only in this response.

  • 400

    validation_error: the body is not JSON, the URL is not a public HTTPS URL on port 443 (or has credentials, or exceeds 2048 characters), description exceeds 100 characters, or events is empty or contains an unknown event.

  • 401

    unauthorized: no Bearer token, or the dashboard session is invalid or expired. invalid_api_key: the API key is unknown or revoked.

  • 402

    webhooks_require_paid_plan: webhooks are available on Starter and Pro.

  • 403

    webhook_management_forbidden: publishable keys cannot manage webhooks. account_suspended: the account is suspended.

  • 404

    no_project: the signed-in account has no project.

  • 409

    webhook_limit_reached: the plan's endpoint limit is used; delete one first. webhook_url_exists: an endpoint with that URL already exists in the project.

  • 429

    rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour Retry-After.

Request
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 pipeline",
  "events": [
    "media.created",
    "media.deleted",
    "export.completed",
    "export.failed"
  ]
}'
Response 201
{
  "data": {
    "id": "whk_abc123",
    "url": "https://api.example.com/pixelvault-events",
    "description": "media pipeline",
    "events": [
      "media.created",
      "media.deleted",
      "export.completed",
      "export.failed"
    ],
    "active": true,
    "created_at": "2026-11-16T12:00:00.000Z",
    "updated_at": "2026-11-16T12:00:00.000Z",
    "signing_secret": "whsec_Qm9vZ2llV29vZ2llQm9vZ2llV29vZ2ll"
  }
}

Update a webhook endpoint

PATCH /v1/webhooks/{id}

Change an endpoint's url, description, events or active flag; omitted fields keep their value. Set active: false to pause deliveries without losing the configuration. The signing secret is unchanged.

Authentication

API key, or a dashboard session token, sent as Authorization: Bearer <token>.

Path parameters

Path parameters
Name Type Required Description
id string Required

Webhook endpoint id.

Request body

application/json, required

Request body
Name Type Required Description
url string (uri) Optional

New public HTTPS URL on port 443.

max length 2048

description string nullable Optional

New label; null or an empty string clears it.

max length 100

events array of string Optional

Replaces the subscribed event types.

One of: media.created, media.deleted, image.description.completed, image.description.failed, export.completed, export.failed, video.optimization.completed, video.optimization.failed, video.enrichment.completed, video.enrichment.failed, audio.enrichment.completed, audio.enrichment.failed

min items 1

active boolean Optional

False pauses deliveries.

Responses

  • 200

    Updated endpoint

  • 400

    validation_error: the body is not JSON or has none of url, description, events, active, or a field is invalid (see create_webhook).

  • 401

    unauthorized: no Bearer token, or the dashboard session is invalid or expired. invalid_api_key: the API key is unknown or revoked.

  • 403

    webhook_management_forbidden: publishable keys cannot manage webhooks. account_suspended: the account is suspended.

  • 404

    not_found: no webhook with this id in the project. no_project: the signed-in account has no project.

  • 409

    webhook_url_exists: another endpoint in the project already uses that URL.

  • 429

    rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour Retry-After.

Request
curl -X PATCH https://api.pixelvault.dev/v1/webhooks/whk_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://api.example.com/pixelvault-events",
  "description": "media pipeline",
  "events": [
    "media.created",
    "media.deleted"
  ],
  "active": false
}'
Response 200
{
  "data": {
    "id": "whk_abc123",
    "url": "https://api.example.com/pixelvault-events",
    "description": "media pipeline",
    "events": [
      "media.created",
      "media.deleted",
      "export.completed",
      "export.failed"
    ],
    "active": true,
    "created_at": "2026-11-16T12:00:00.000Z",
    "updated_at": "2026-11-16T12:00:00.000Z"
  }
}

Delete a webhook endpoint and its delivery log

DELETE /v1/webhooks/{id}

Permanently delete an endpoint. Its delivery log is deleted with it and nothing more is delivered to it.

Authentication

API key, or a dashboard session token, sent as Authorization: Bearer <token>.

Path parameters

Path parameters
Name Type Required Description
id string Required

Webhook endpoint id.

Responses

  • 200

    Deleted

  • 401

    unauthorized: no Bearer token, or the dashboard session is invalid or expired. invalid_api_key: the API key is unknown or revoked.

  • 403

    webhook_management_forbidden: publishable keys cannot manage webhooks. account_suspended: the account is suspended.

  • 404

    not_found: no webhook with this id in the project. no_project: the signed-in account has no project.

  • 429

    rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour Retry-After.

Request
curl -X DELETE https://api.pixelvault.dev/v1/webhooks/whk_abc123 \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
Response 200
{
  "data": {
    "deleted": true
  }
}

Rotate a webhook signing secret

POST /v1/webhooks/{id}/rotate-secret

Immediately invalidates the previous signing secret and returns the replacement once. Deliveries signed after the rotation use the new secret, so update your verifier first or accept both briefly.

Authentication

API key, or a dashboard session token, sent as Authorization: Bearer <token>.

Path parameters

Path parameters
Name Type Required Description
id string Required

Webhook endpoint id.

Responses

  • 200

    Secret rotated

  • 401

    unauthorized: no Bearer token, or the dashboard session is invalid or expired. invalid_api_key: the API key is unknown or revoked.

  • 403

    webhook_management_forbidden: publishable keys cannot manage webhooks. account_suspended: the account is suspended.

  • 404

    not_found: no webhook with this id in the project. no_project: the signed-in account has no project.

  • 429

    rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour Retry-After.

Request
curl -X POST https://api.pixelvault.dev/v1/webhooks/whk_abc123/rotate-secret \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
Response 200
{
  "data": {
    "id": "whk_abc123",
    "signing_secret": "whsec_Qm9vZ2llV29vZ2llQm9vZ2llV29vZ2ll"
  }
}

Inspect recent webhook deliveries

GET /v1/webhooks/{id}/deliveries

Newest-first delivery attempts for one endpoint, retained for 30 days. Each entry stores the status, attempt count, last response code and a bounded error message; response bodies and signing secrets are never stored. CLI: pixelvault webhooks deliveries <id>.

Authentication

API key, or a dashboard session token, sent as Authorization: Bearer <token>.

Path parameters

Path parameters
Name Type Required Description
id string Required

Webhook endpoint id.

Query parameters

Query parameters
Name Type Required Description
limit integer Optional

Deliveries to return; out-of-range values are clamped to 1–100.

Default: 50

min 1 · max 100

Responses

  • 200

    Delivery log

  • 401

    unauthorized: no Bearer token, or the dashboard session is invalid or expired. invalid_api_key: the API key is unknown or revoked.

  • 403

    webhook_management_forbidden: publishable keys cannot manage webhooks. account_suspended: the account is suspended.

  • 404

    not_found: no webhook with this id in the project. no_project: the signed-in account has no project.

  • 429

    rate_limit_exceeded: more than 60 requests per minute for this key (or dashboard session) or 300 per minute for the project. Honour Retry-After.

Request
curl https://api.pixelvault.dev/v1/webhooks/whk_abc123/deliveries \
  -H "Authorization: Bearer $PIXELVAULT_API_KEY"
Response 200
{
  "data": [
    {
      "id": "whd_abc123",
      "event_id": "whe_abc123",
      "event": "media.created",
      "status": "delivered",
      "attempts": 1,
      "response_status": 200,
      "error": null,
      "next_attempt_at": null,
      "last_attempt_at": "2026-11-16T12:00:01.000Z",
      "delivered_at": "2026-11-16T12:00:01.000Z",
      "created_at": "2026-11-16T12:00:00.000Z"
    }
  ]
}