Webhooks

Register HTTP endpoints to receive real-time notifications when transcoding jobs complete, fail, or change status.

List Webhooks

GET /api/v1/webhooks/

Returns all webhooks owned by the authenticated user.

Create Webhook

POST /api/v1/webhooks/

Request Body

{
  "url": "https://your-app.com/hooks/transcode",
  "events": ["job.completed", "job.failed"],
  "secret": "your_signing_secret"
}

Response

{
  "id": "uuid",
  "url": "https://your-app.com/hooks/transcode",
  "events": ["job.completed", "job.failed"],
  "is_active": true,
  "created_at": "2026-04-23T10:00:00Z"
}

Update Webhook

PUT /api/v1/webhooks/{webhook_id}

Update the URL, events, or active status of an existing webhook.

Delete Webhook

DELETE /api/v1/webhooks/{webhook_id}

View Delivery History

GET /api/v1/webhooks/{webhook_id}/deliveries

Returns the delivery log for a specific webhook, including HTTP status codes and response times. Useful for debugging failed deliveries.

Test Webhook

POST /api/v1/webhooks/{webhook_id}/test

Sends a test payload to the webhook URL to verify connectivity. The test event uses a synthetic job payload so no real data is affected.

Webhook Payload

When an event fires, the platform sends a POST request to your URL with this payload:

{
  "event": "job.completed",
  "timestamp": "2026-04-23T14:30:00Z",
  "data": {
    "job_id": "b82542ee-...",
    "status": "completed",
    "output_format": "aac",
    "output_url": "/api/v1/stream/download/processed/file.aac",
    "duration_seconds": 174.5
  }
}

Signature Verification

Each delivery includes an X-Webhook-Signature header containing an HMAC-SHA256 signature computed with your secret. Verify it server-side to ensure authenticity:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}