Developer docs

Webhooks

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

On this page

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. A webhook is attempted at most 3 times in total: after the third failed attempt it is marked as failed and no longer retried. Logs of the webhook calls can be reviewed in the webhook dashboard.

Webhook delivery and retries When an event occurs in MediaLab, the webhook is posted to your HTTPS endpoint. A 2XX response means it was delivered. Any other status is retried automatically with the same event id, up to 3 attempts in total. After the third failed attempt the webhook is marked as failed and is not retried again. Every call is logged in the webhook dashboard. WEBHOOK DELIVERY Event in MediaLabe.g. file_uploadPOST to your endpointHTTPS, hosted by you2XX responsedeliveredAny other statusretried automatically retry · max 3 attempts in total · same event id after 3attemptsFailednot retried again Every call is logged in the webhook dashboard.

Events

  1. file_approval - when file approval status changes.
  2. file_comment - when a comment is added.
  3. file_push - when a push record has been processed.
  4. file_qc - when file QC status changes.
  5. file_transcode - when a transcode workflow has finished.
  6. file_transcribe - when a transcription has finished.
  7. file_trash - when a file is moved to the trash.
  8. file_upload - when a new file has been uploaded.
  9. folder_trash - when a folder is moved to the trash.

Structure

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

  1. timestamp - unix timestamp of webhook.
  2. token - generated randomized token for webhook.
  3. signature - HMAC computed with SHA256 hash of CONCAT(timestamp, token) signed using endpoint-specific key.
  4. id - UUID for event, remains identical across retries.
  5. event - event name.
(
[signature] => Array
    (
        [timestamp] => Integer
        [token] => String
        [signature] => String
    )

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

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.

Validating a webhook signature Concatenate the timestamp and token from the signature block, compute an HMAC with SHA256 using the key of your webhook destination, and compare the result with the signature. If they match, the webhook was sent and signed by MediaLab. SIGNATURE CHECK, ON YOUR SERVER timestamp + tokenfrom the signature blockHMAC-SHA256keyed with your endpoint keyCompare with signatureMatchsent and signed by MediaLab The key is specific to 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);
$signature = (array) ($request_data['signature'] ?? []);
$expected = hash_hmac('sha256', ($signature['timestamp'] ?? '') . ($signature['token'] ?? ''), $webhook_key);
if (hash_equals($expected, (string) ($signature['signature'] ?? ''))) {
    echo 'Signature validated';
}