Webhook 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 acces 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.

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

Webhook 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
    )

)
					

Webhook 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';
}