Webhooks

Webhooks allow you to receive real-time notifications about events happening in your Ignite workspace. Instead of polling the API for changes, webhooks push data to your server as events occur.

What are Webhooks?

Webhooks are HTTP callbacks that are triggered when specific events occur. When an event happens (like a video being created or updated), Ignite sends an HTTP POST request to your configured endpoint with information about the event.

Use Cases

CMS Synchronization — Keep your external content management system in sync with video changes
Workflow Automation — Trigger automated workflows when videos are created, updated, or deleted
Notifications — Send alerts to your team when video processing is complete
Analytics — Track video lifecycle events in your own analytics system

How it Works

Create a Webhook Subscription

Configure a webhook subscription in your Ignite Admin UI. You'll need to provide:

A URL endpoint on your server that can receive HTTP POST requests
The event types you want to subscribe to

Receive Events

When a subscribed event occurs, Ignite sends an HTTP POST request to your endpoint with:

The event type in the X-Webhook-Event header
A signature for verification in the X-Webhook-Signature header
A unique delivery ID in the X-Webhook-Delivery-Id header
The complete video object as the JSON body

Process and Respond

Your endpoint should:

Verify the webhook signature
Process the event data
Return a 2xx status code within 30 seconds

⚠️

Webhooks may arrive out of order or be delivered more than once. Your client is responsible for checking the updatedAt timestamp and the video id to ensure correct ordering and data consistency. Always compare the incoming timestamp against your stored data before applying updates, and use the X-Webhook-Delivery-Id header to detect and skip duplicate deliveries.

Webhook Subscription

A webhook subscription is a configuration that defines where events should be sent and which events to listen for.

Subscription Properties

Property	Type	Description
`id`	string	Unique identifier for the subscription
`url`	string	The endpoint URL where events will be sent (HTTP or HTTPS)
`events`	object	Which event types are enabled
`events.videoCreated`	boolean	Receive events when videos are created
`events.videoUpdated`	boolean	Receive events when videos are updated
`events.videoDeleted`	boolean	Receive events when videos are deleted
`active`	boolean	Whether the webhook is currently active
`signingSecret`	string	Secret key used for signature verification (auto-generated)
`workspace`	string	The workspace this webhook belongs to

Example Subscription Object

{
  "id": "507f1f77bcf86cd799439011",
  "url": "https://your-server.com/webhook",
  "events": {
    "videoCreated": true,
    "videoUpdated": true,
    "videoDeleted": false
  },
  "active": true,
  "signingSecret": "whsec_abc123...",
  "workspace": "507f1f77bcf86cd799439000"
}

HTTP Request Format

When an event occurs, Ignite sends a POST request to your endpoint:

Headers

Header	Description
`Content-Type`	`application/json`
`X-Webhook-Event`	The event type (e.g., `video.created`)
`X-Webhook-Signature`	HMAC-SHA256 signature for verification
`X-Webhook-Delivery-Id`	Unique identifier for this delivery (useful for idempotency)

Body

The request body contains the complete video object as JSON. See the Video Object documentation for the full structure.

{
  "id": "507f1f77bcf86cd799439011",
  "title": "My Video",
  "status": "COMPLETE",
  "visibility": "public",
  "duration": 120,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  // ... all other video properties
}

Next Steps

Event Types — Learn about the available event types
Signature Verification — Secure your webhook endpoint
Examples — See full implementation examples

Querying Event Types