Overview
The Webhook API allows you to receive real-time notifications about events that occur in your MediaZilla account.
When an event is triggered, an HTTP POST request is sent to your configured webhook URL with a JSON payload containing the event details.
How It Works
Subscription
Create a webhook subscription by providing a URL endpoint where notifications will be sent.Triggers
Choose which event types you want to subscribe to (for example:presentation.created,order.completed).Event Delivery
When a subscribed event occurs, a webhook event is created and delivered asynchronously to your endpoint.
Webhook Body Structure
All webhook requests follow the same base structure.
{
"id": "event-uuid",
"type": "event.type",
"created_at": "2024-01-15T10:30:00Z",
"data": {
// Event-specific data
}
}Base fields
id (string, UUID): Unique identifier of the webhook event
type (string): Event type (e.g.
presentation.created,order.completed)created_at (string, ISO8601): Timestamp when the event was created
data (object): Event-specific payload (varies by event type)
Event Types
Presentation Events
presentation.created
Triggered when a new presentation is created.
Event type: presentation.created
{
"id": "uuid",
"type": "presentation.created",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"presentation": {
"id": "uuid",
"title": "Presentation Title",
"path": "/path/to/presentation",
"created_at": "2024-01-15T10:30:00Z"
}
}
}Data fields (data.presentation)
id (UUID)
title (string)
path (string)
created_at (ISO8601)
presentation.published
Triggered when a presentation is published.
Event type: presentation.published
{
"id": "uuid",
"type": "presentation.published",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"presentation": {
"id": "uuid",
"title": "Presentation Title",
"path": "/path/to/presentation",
"published_at": "2024-01-15T10:30:00Z"
}
}
}Data fields (data.presentation)
id (UUID)
title (string)
path (string)
published_at (ISO8601)
Video Events
video.upload.started
Triggered when a video upload starts.
Event type: video.upload.started
{
"id": "uuid",
"type": "video.upload.started",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"video": {
"id": "uuid",
"title": "Video Title",
"path": "/path/to/video",
"upload_started_at": "2024-01-15T10:30:00Z"
}
}
}video.upload.completed
Triggered when a video upload completes successfully.
Event type: video.upload.completed
{
"id": "uuid",
"type": "video.upload.completed",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"video": {
"id": "uuid",
"title": "Video Title",
"path": "/path/to/video",
"upload_completed_at": "2024-01-15T10:30:00Z"
}
}
}video.transcode.started
Triggered when video transcoding starts.
Event type: video.transcode.started
{
"id": "uuid",
"type": "video.transcode.started",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"video": {
"id": "uuid",
"title": "Video Title",
"path": "/path/to/video",
"transcode_started_at": "2024-01-15T10:30:00Z"
}
}
}video.transcode.completed
Triggered when video transcoding completes successfully.
Event type: video.transcode.completed
{
"id": "uuid",
"type": "video.transcode.completed",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"video": {
"id": "uuid",
"title": "Video Title",
"path": "/path/to/video",
"transcode_completed_at": "2024-01-15T10:30:00Z"
}
}
}Add-on Events
addon.created
Triggered when a new add-on is created.
Event type: addon.created
{
"id": "uuid",
"type": "addon.created",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"addon": {
"id": "uuid",
"title": "Addon Title",
"price": 9.99,
"currency": "USD",
"created_at": "2024-01-15T10:30:00Z",
"content": {
"type": "Video",
"id": "uuid",
"title": "Content Title"
},
"presentation": {
"id": "uuid",
"title": "Presentation Title",
"path": "/path/to/presentation"
}
}
}
}addon.updated
Triggered when an add-on is updated.
Event type: addon.updated
{
"id": "uuid",
"type": "addon.updated",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"addon": {
"id": "uuid",
"title": "Addon Title",
"price": 9.99,
"currency": "USD",
"updated_at": "2024-01-15T10:30:00Z",
"content": {
"type": "Video",
"id": "uuid",
"title": "Content Title"
},
"presentation": {
"id": "uuid",
"title": "Presentation Title",
"path": "/path/to/presentation"
}
}
}
}Order Events
order.completed
Triggered when an order is completed.
Event type: order.completed
{
"id": "uuid",
"type": "order.completed",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"order": {
"id": "uuid",
"total_amount": 29.99,
"currency": "USD",
"status": "completed",
"source": "presentation",
"completed_at": "2024-01-15T10:30:00Z",
"purchaser": {
"email": "customer@example.com"
}
}
}
}Delivery Events
delivery.sent
Triggered when a digital delivery is sent.
Event type: delivery.sent
{
"id": "uuid",
"type": "delivery.sent",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"delivery": {
"id": "uuid",
"sent_at": "2024-01-15T10:30:00Z",
"content": {
"id": "uuid",
"type": "Video",
"title": "Content Title",
"path": "/path/to/content",
"allow_download": true
}
}
}
}delivery.accepted
Triggered when a digital delivery is accepted by the recipient.
Event type: delivery.accepted
{
"id": "uuid",
"type": "delivery.accepted",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"delivery": {
"id": "uuid",
"accepted_at": "2024-01-15T10:30:00Z",
"recipient": {
"email": "recipient@example.com"
},
"content": {
"id": "uuid",
"type": "Video",
"title": "Content Title",
"path": "/path/to/content",
"allow_download": true
}
}
}
}Webhook Delivery
HTTP method: POST
Content-Type: application/json
Headers
Content-Type: application/json
X-Webhook-Password (only if configured)
Always validate the X-Webhook-Password header to ensure the request is authentic.
Response Handling
Your endpoint should:
Return a 2xx status code
Process events asynchronously
Be idempotent
Respond within 5 seconds
Retry Logic
Maximum attempts: 3
Retry delays:
After first failure: 30 minutes
After second failure: 2 hours
After third failure: no further retries
The same webhook event ID is used on retries.
Best Practices
Validate webhook authenticity
Handle duplicate events safely
Log incoming webhooks
Use HTTPS
Prepare for bursts of events
Event Type Reference
presentation.created
presentation.published
video.upload.started
video.upload.completed
video.transcode.started
video.transcode.completed
addon.created
addon.updated
order.completed
delivery.sent
delivery.accepted
Data Types
UUID: All IDs are UUID strings
Timestamps: ISO8601, UTC
Currency codes: ISO 4217 (USD, EUR, GBP)
Support
For questions or issues related to webhooks, contact MediaZilla support or refer to the main API documentation.