Manage Webhooks

Create and manage webhook subscriptions through the API, rather than only in the dashboard - so an integration can provision its own delivery endpoint at install time.

For what the deliveries look like and how to verify them, see Overview, Events and Signatures.

List webhooks

GET /v1/webhooks

curl https://api.vidocu.ai/v1/webhooks \
  -H "Authorization: Bearer vdo_live_your_key_here"

{
  "webhooks": [
    {
      "id": "whk_9f2c41ab77e04d3b8a16",
      "url": "https://example.com/hooks/vidocu",
      "events": ["export.completed", "export.failed"],
      "enabled": true,
      "consecutiveFailures": 0,
      "lastDeliveredAt": "2026-08-09T10:31:00.000Z",
      "lastFailedAt": null,
      "createdAt": "2026-08-01T09:00:00.000Z",
      "updatedAt": "2026-08-01T09:00:00.000Z"
    }
  ]
}

Secrets are not included here. See below.

Create a webhook

POST /v1/webhooks

curl -X POST https://api.vidocu.ai/v1/webhooks \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/vidocu",
    "events": ["export.completed", "export.failed"]
  }'

Response 201 Created

{
  "id": "whk_9f2c41ab77e04d3b8a16",
  "url": "https://example.com/hooks/vidocu",
  "events": ["export.completed", "export.failed"],
  "enabled": true,
  "secret": "8f14e45fceea167a5a36dedd4bea2543..."
}

Store the secret now

secret is returned only in this response. It signs every delivery, and you need it to verify them - so if it echoed on every read, any read-only token would be enough to forge a signed payload. If you lose it, delete the webhook and create a new one.

HTTPS is required. A plain-HTTP endpoint would receive signed payloads, and their contents, in the clear.

Update a webhook

PATCH /v1/webhooks/:id

Change the url, replace the events list, or set enabled.

curl -X PATCH https://api.vidocu.ai/v1/webhooks/whk_9f2c41ab77e04d3b8a16 \
  -H "Authorization: Bearer vdo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Vidocu disables a webhook after repeated delivery failures. Re-enabling one also resets its failure count, so a webhook you've fixed doesn't trip again on its next hiccup.

Delete a webhook

DELETE /v1/webhooks/:id

Deliveries stop immediately, and the signing secret is gone - recreating the webhook issues a new one.

Errors

Status	Code	Cause
400	validation_error	Invalid URL, non-HTTPS URL, or no events
401	authentication_error	Invalid or missing API key
403	insufficient_role	The workspace role behind the token can't change workspace settings
404	not_found	Webhook not found or belongs to another workspace