Skip to main content

Webhooks

Get real-time notifications about events in your MediaZilla account. Covers webhook setup, payload structure, event types and retries.

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

  1. 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.

  2. Triggers
    Choose which event types you want to subscribe to (for example: presentation.created, order.completed).

  3. 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

  1. Go to Settings → Integrations.

  2. On Custom Integration, open the menu and choose Create.

  3. Enter a Webhook Title and the Webhook URL, choose the events, and click Create.

  4. 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, or rental when any item in the order is a rental

  • amount_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 orders

  • tax_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, or collection for a presentation) and amount paid, in the same unit. An item whose content was deleted keeps its amount; its title and id may be null

  • total_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 paid

  • source (string): the type of the first item, video or collection

  • purchaser.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 request

  • X-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.

  1. Read the raw request body exactly as received, before parsing the JSON.

  2. Split X-MediaZilla-Signature on commas. t is a Unix timestamp in seconds; v1 is the signature.

  3. 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.

  4. Compare it with v1 using a constant-time comparison. If the header has more than one v1, accept the request when any of them matches.

  5. Reject the request if t is 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.

Did this answer your question?