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. Every request is signed, so you can check that it came from MediaZilla and was not changed on the way.
How It Works
Subscription
Create a webhook subscription by providing a URL endpoint where notifications will be sent. MediaZilla generates a signing secret for it and shows it to you once.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, signed with your secret.
Creating a Webhook
Go to Settings → Integrations.
On Custom Integration, open the menu and choose Create.
Enter a Webhook Title and the Webhook URL, choose the events, and click Create.
The Webhook Signing Secret window shows the secret, which starts with
whsec_. Click Copy and store it where your endpoint can read it. It is not shown again.
To get a new secret, choose List on Custom Integration, open the menu next to the webhook and choose Rotate Secret. Deliveries are signed with the new secret immediately, including retries of earlier events, so update your endpoint right away.
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",
"type": "rental",
"status": "confirmed",
"source": "collection",
"total_amount": 40.0,
"currency": "USD",
"amount_charged": 1308,
"tax_amount": 108,
"amount_currency": "usd",
"items": [
{
"id": "uuid",
"title": "Content Title",
"type": "video",
"amount": 1200
}
],
"completed_at": "2024-01-15T10:30:00Z",
"purchaser": {
"email": "customer@example.com"
}
}
}
}Data fields (data.order)
type (string):
purchase, orrentalwhen any item in the order is a rentalamount_charged (integer or null): what the buyer paid, tax included, in the smallest unit of
amount_currency(1308 means 13.08). Null for some older orderstax_amount (integer): the tax in that order, in the same unit; 0 when no tax was charged
amount_currency (string): the currency the buyer paid in, lower case
items (array): one entry per item bought, with its id, title, type (
video, orcollectionfor a presentation) and amount paid, in the same unit. An item whose content was deleted keeps its amount; its title and id may be nulltotal_amount (number): the sum of the items' list prices in
currency, in whole units. It does not reflect rentals, discounts or tax; use amount_charged for what was paidsource (string): the type of the first item,
videoorcollectionpurchaser.email (string): the buyer's email address
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-MediaZilla-Signature:
t=<timestamp>,v1=<signature>, the signature of this requestX-MediaZilla-Event-Id: the event's id, the same as in the body and the same on every retry
Verifying Requests
Check the signature on every request before you trust it. A request that fails the check did not come from MediaZilla, or was changed on the way, and should be rejected.
Read the raw request body exactly as received, before parsing the JSON.
Split X-MediaZilla-Signature on commas.
tis a Unix timestamp in seconds;v1is the signature.Compute an HMAC-SHA256, using your signing secret (the whole value, including
whsec_) as the key and<t>.<raw body>as the message, and write it as lowercase hex.Compare it with
v1using a constant-time comparison. If the header has more than onev1, accept the request when any of them matches.Reject the request if
tis more than 5 minutes from your server's clock, so an old request can't be replayed.
Example in Python:
import hashlib, hmac, time
def is_valid(secret, raw_body, header, tolerance=300):
parts = [p.split("=", 1) for p in header.split(",")]
timestamp = int(dict(parts)["t"])
if abs(time.time() - timestamp) > tolerance:
return False
message = f"{timestamp}.".encode() + raw_body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(expected, value) for key, value in parts if key == "v1")
Each attempt, including a retry, is signed with a fresh timestamp, so retries pass the time check.
Response Handling
Your endpoint should:
Return a 2xx status code
Process events asynchronously
Be idempotent
Respond within 5 seconds
Retry Logic
If your endpoint doesn't return a 2xx status, or can't be reached, the event is retried up to 3 times:
First retry: 30 minutes after the first failure
Second retry: 2 hours after the second failure
Third retry: 5 hours after the third failure
After a fourth failure, the event is not sent again
The same webhook event ID is used on retries.
Best Practices
Verify the X-MediaZilla-Signature header on every request
Keep your signing secret out of source code, and rotate it if it may have been exposed
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.
