Webhooks API for delivery events

Summary

Webhooks deliver VideoVector events to your HTTPS endpoint for review operations, export handoff, import monitoring, and media processing automation.

Webhook endpoints

Method	Path	Purpose
`POST`	`/api/v2/webhooks`	Create a webhook
`GET`	`/api/v2/webhooks`	List webhooks
`GET`	`/api/v2/webhooks/events`	List supported event names
`GET`	`/api/v2/webhooks/{webhook_id}`	Retrieve one webhook
`PATCH`	`/api/v2/webhooks/{webhook_id}`	Update a webhook
`DELETE`	`/api/v2/webhooks/{webhook_id}`	Delete a webhook
`POST`	`/api/v2/webhooks/{webhook_id}/rotate-secret`	Rotate the signing secret
`POST`	`/api/v2/webhooks/{webhook_id}/test`	Send a test event
`GET`	`/api/v2/webhooks/{webhook_id}/deliveries`	List deliveries
`GET`	`/api/v2/webhooks/deliveries/{delivery_id}`	Retrieve one delivery
`POST`	`/api/v2/webhooks/deliveries/{delivery_id}/retry`	Retry a failed delivery

Event model

The public SDK lists these supported event names:

media.created
media.processing.started
media.processing.completed
media.processing.failed
prompt_run.started
prompt_run.completed
prompt_run.failed
prompt_run.cancelled
prompt_run.partial_completed
prompt_run.progress
export.ready
export.failed
import_job.started
import_job.completed
import_job.failed
import_job.partial_completed
import_job.progress

Example: create a webhook

curl -X POST /api/v2/webhooks \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-review-events" \
  -d '{
    "name": "Review operations",
    "url": "https://example.com/webhooks/videovector",
    "events": ["prompt_run.completed", "export.ready"],
    "index_ids": ["idx_archive"],
    "metadata": {"owner":"review-ops"}
  }'

Delivery headers and signature verification

Webhook deliveries include:

X-Webhook-Signature
X-Webhook-ID
X-Delivery-ID
X-Event-Type

The delivery worker signs the canonical JSON payload with HMAC-SHA256 and sends the header as sha256=<hex-digest>.

import hashlib
import hmac
import json

payload_json = json.dumps(payload, sort_keys=True)
expected = hmac.new(secret.encode("utf-8"), payload_json.encode("utf-8"), hashlib.sha256).hexdigest()
assert received_signature == f"sha256={expected}"

Delivery status and recovery

The delivery worker treats response classes differently:

2xx: success
4xx: permanent failure, no automatic retry
5xx and network failures: retryable failure

Use POST /api/v2/webhooks/deliveries/{delivery_id}/retry when the downstream issue is resolved.

Secret rotation

POST /api/v2/webhooks/{webhook_id}/rotate-secret returns a new secret. Update the receiving system before you depend on the next production delivery.