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
| Property | Type | Description |
|---|---|---|
id | string | Endpoint id ( |
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. |
active | boolean | Inactive endpoints keep their configuration but receive nothing; queued deliveries are marked |
created_at | string (date-time) | |
updated_at | string (date-time) |
{
"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. HonourRetry-After.
curl https://api.pixelvault.dev/v1/webhooks \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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.sourceisupload,url_import,claim,generationoreditmedia.deleted: identifies the deleted asset (withreasonanddeleted_at) but deliberately omits its now-dead URLimage.description.completed/image.description.failedexport.completed/export.failed: carries the export'sstatus_urland, when complete,download_urlvideo.optimization.completed/video.optimization.failedvideo.enrichment.completed/video.enrichment.failedaudio.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
| 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. |
description | string nullable | Optional | Free-text label. |
events | array of string | Optional | Event types to deliver. Omit for all. |
Responses
- 201
Endpoint created;
signing_secretis 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),descriptionexceeds 100 characters, oreventsis 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. HonourRetry-After.
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"
]
}' {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Webhook endpoint id. |
Request body
| Name | Type | Required | Description |
|---|---|---|---|
url | string (uri) | Optional | New public HTTPS URL on port 443. |
description | string nullable | Optional | New label; null or an empty string clears it. |
events | array of string | Optional | Replaces the subscribed event types. |
active | boolean | Optional | False pauses deliveries. |
Responses
- 200
Updated endpoint
- 400
validation_error: the body is not JSON or has none ofurl,description,events,active, or a field is invalid (seecreate_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. HonourRetry-After.
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
}' {
"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
| 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. HonourRetry-After.
curl -X DELETE https://api.pixelvault.dev/v1/webhooks/whk_abc123 \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| 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. HonourRetry-After.
curl -X POST https://api.pixelvault.dev/v1/webhooks/whk_abc123/rotate-secret \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Webhook endpoint id. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Deliveries to return; out-of-range values are clamped to 1–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. HonourRetry-After.
curl https://api.pixelvault.dev/v1/webhooks/whk_abc123/deliveries \
-H "Authorization: Bearer $PIXELVAULT_API_KEY" {
"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"
}
]
}