Developer Docs

Webhooks

Receive real-time HTTP notifications when key events happen in MediaLab - uploads, approvals, transcodes, and more.

Webhooks

Overview

Webhooks can be registered to be notified when certain events occur within MediaLab. For each configured event, relevant data is pushed to an HTTPS endpoint hosted by the receiver. Only events and media that the user has access to will trigger a webhook as the webhook runs in the security context of the user account.

The webhook endpoint must respond with HTTP status 2XX. Any other status will result in an automated retry of the webhook, up to 3 times. After 3 times the webhook will be marked as failed and will no longer be retried. Logs of the webhook calls can be reviewed in the webhook dashboard.

Webhooks

Events

file_approval when file approval status changes
file_comment when a comment is added.
file_push when a push record has been processed.
file_qc when file QC status changes.
file_transcode when a transcode workflow has finished.
file_transcribe when a transcription has finished.
file_trash when a file is moved to the trash.
file_upload when a new file has been uploaded.
folder_trash when a folder is moved to the trash.

Webhooks

Structure

Each webhook has a standardized structure with one `data` key that holds event-specific data.

timestamp unix timestamp of webhook.
token generated randomized token for webhook.
signature HMAC computed with SHA256 hash of CONCAT(timestamp, token) signed using endpoint-specific key .
id UUID for event, remains identical across retries.
event event name

(
[signature] => Array
    (
        [timestamp] => Integer
        [token] => String
        [signature] => String
    )

[id] => String(UUID)
[event] => String
[api_version] => Date(YYYY-MM-DD)
[data] => Array
)

Webhooks

Validation

Each webhook contains a `signature` block that can be used to verify the webhook was sent and signed by us. The signature is a computed HMAC with the SHA256 hash function of CONCAT(timestamp, token). The key used is specific for each webhook destination and can be retrieved from the dashboard.

?php
$webhook_key = 'SECRET_KEY';
$request_data = json_decode(file_get_contents('php://input'), true);
$data = [
'id' => (string) $request_data['id'] ?: '',
'signature' => (array) $request_data['signature'] ?: [],
'event' => (string) $request_data['event'] ?: '',
'data' => (array) $request_data['data'] ?: [],
];
if (hash_equals($webhook_data['signature']['signature'], hash_hmac(
'sha256', $webhook_data['signature']['timestamp'] . $webhook_data['signature']['token'], $webhook_key
))) {
echo 'Signature validated';
}