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

[API reference](/docs/api/)

# 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](#object)
-   GET [List webhook endpoints](#list_webhooks)
-   POST [Create a webhook endpoint](#create_webhook)
-   PATCH [Update a webhook endpoint](#update_webhook)
-   DELETE [Delete a webhook endpoint and its delivery log](#delete_webhook)
-   POST [Rotate a webhook signing secret](#rotate_webhook_secret)
-   GET [Inspect recent webhook deliveries](#list_webhook_deliveries)

## 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`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`webhook_management_forbidden`](/docs/errors/#webhook_management_forbidden): publishable keys cannot manage webhooks. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    `no_project`: the signed-in account has no project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#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

curlNode.jsPythonCLI

```
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`](/docs/api/webhooks/#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`](/docs/api/webhooks/#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`](/docs/api/videos/#get_video) and [`get_audio`](/docs/api/audio/#get_audio) remains supported. Runnable Node 20 verifiers: [video-enrichment-webhook.mjs](https://pixelvault.dev/examples/video-enrichment-webhook.mjs) and [audio-enrichment-webhook.mjs](https://pixelvault.dev/examples/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`](/docs/errors/#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`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   402
    
    [`webhooks_require_paid_plan`](/docs/errors/#webhooks_require_paid_plan): webhooks are available on Starter and Pro.
    
-   403
    
    [`webhook_management_forbidden`](/docs/errors/#webhook_management_forbidden): publishable keys cannot manage webhooks. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    `no_project`: the signed-in account has no project.
    
-   409
    
    [`webhook_limit_reached`](/docs/errors/#webhook_limit_reached): the plan's endpoint limit is used; delete one first. [`webhook_url_exists`](/docs/errors/#webhook_url_exists): an endpoint with that URL already exists in the project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#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

curlNode.jsPythonCLI

```
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`](/docs/errors/#validation_error): the body is not JSON or has none of `url`, `description`, `events`, `active`, or a field is invalid (see [`create_webhook`](/docs/api/webhooks/#create_webhook)).
    
-   401
    
    [`unauthorized`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`webhook_management_forbidden`](/docs/errors/#webhook_management_forbidden): publishable keys cannot manage webhooks. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`not_found`](/docs/errors/#not_found): no webhook with this id in the project. `no_project`: the signed-in account has no project.
    
-   409
    
    [`webhook_url_exists`](/docs/errors/#webhook_url_exists): another endpoint in the project already uses that URL.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#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

curlNode.jsPython

```
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`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`webhook_management_forbidden`](/docs/errors/#webhook_management_forbidden): publishable keys cannot manage webhooks. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`not_found`](/docs/errors/#not_found): no webhook with this id in the project. `no_project`: the signed-in account has no project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#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

curlNode.jsPython

```
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`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`webhook_management_forbidden`](/docs/errors/#webhook_management_forbidden): publishable keys cannot manage webhooks. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`not_found`](/docs/errors/#not_found): no webhook with this id in the project. `no_project`: the signed-in account has no project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#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

curlNode.jsPython

```
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`](/docs/errors/#unauthorized): no Bearer token, or the dashboard session is invalid or expired. [`invalid_api_key`](/docs/errors/#invalid_api_key): the API key is unknown or revoked.
    
-   403
    
    [`webhook_management_forbidden`](/docs/errors/#webhook_management_forbidden): publishable keys cannot manage webhooks. [`account_suspended`](/docs/errors/#account_suspended): the account is suspended.
    
-   404
    
    [`not_found`](/docs/errors/#not_found): no webhook with this id in the project. `no_project`: the signed-in account has no project.
    
-   429
    
    [`rate_limit_exceeded`](/docs/errors/#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

curlNode.jsPythonCLI

```
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"
    }
  ]
}
```
