Webhooks
Receive real-time notifications when events occur in your workspace instead of polling the Jobs endpoint.
How it works
- Register a webhook URL from the Vidocu Dashboard
- Select which events to subscribe to
- Vidocu sends an HTTP POST to your URL when events fire
- Your server responds with a
2xxstatus to acknowledge delivery
Webhook limits by plan
| Plan | Max webhooks |
|---|---|
| Starter | 3 |
| Growth | 10 |
| Scale | 25 |
| Enterprise | Unlimited |
Delivery
Webhooks are delivered as POST requests with a JSON body:
{
"event": "video.analyzed",
"data": { ... },
"webhookId": "wh_abc123"
}
Headers
| Header | Description |
|---|---|
Content-Type | application/json |
X-Vidocu-Event | Event type (e.g. video.analyzed) |
X-Vidocu-Signature | HMAC SHA-256 signature for verification |
X-Vidocu-Timestamp | Unix timestamp (seconds) when the event was sent |
X-Vidocu-Delivery-Attempt | Attempt number (1–4) |
Retries
Failed deliveries (non-2xx response or timeout) are retried up to 3 times with increasing delays:
| Attempt | Delay |
|---|---|
| 1st retry | 1 second |
| 2nd retry | 2 seconds |
| 3rd retry | 4 seconds |
Each delivery attempt has a 10-second timeout.
Auto-disable
After 10 consecutive failures, the webhook is automatically disabled. Re-enable it from the dashboard after fixing the endpoint.
Next steps
- Events — All available event types and their payloads
- Signatures — Verify webhook authenticity