Webhooks

Webhooks allow your application to receive updates in real-time, rather than having to constantly poll the Editframe API for new data. This can be more efficient and cost-effective than constantly checking for updates, as it reduces the number of requests that your server has to handle.

Configuring webhooks

To begin receiving webhooks, you must enable the feature within your application. You can enable or disable webhooks directly from the main Editframe dashboard page. Once they have been enabled, you can provide your webhook URL under the Webhooks tab. A webhook will now be fired off by Editframe whenver something notable happens. Let's examine what webhook requests to your server look like.

When submitting your webhook URL, we'll send a test request to ensure that it is valid (we're expecting a 2xx response). If the request fails, we won't send out webhooks until your URL is operational.

Receiving webhooks

When your app receives a webhook request from Editframe, check the event attribute to see what event triggered the request. The first portion of the event is the object type while the second portion is the name of the trigger.

Example webhook payload

{
  "id": "X3Jq5j12GN",
  "event": "video.created",
  "timestamp": 1671228849,
  //...
}

In the example above, a video was triggered by the created event, and the object type is a video.

See all available events

Webhook signing

To know for sure that a webhook was, in fact, sent by Editframe instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named X-Editframe-Signature. The signature is an HMAC hash of the request payload hashed using your API token. Here is an example of how to verify the signature in your applcation:

Verifying a request

const signature = req.headers['X-Editframe-Signature']
const payload = req.rawBody
const secret = process.env.EDITFRAME_API_TOKEN
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

Available events

Name
video.created
Type
Description
A new video was created in our system. This video will begin processing soon.
Name
video.processing
Type
Description
A video is currently being processed by rendering servers.
Name
video.processed
Type
Description
A video has finished processing and can be consumed.
Name
video.failed
Type
Description
A video failed to be proccessed.
Name
flow.processing
Type
Description
A workflow is currently being processed by worker servers.
Name
flow.processed
Type
Description
A workflow has finished processing and its deliverables are available.
Name
transcription.created
Type
Description
A new transcription was created in our system.
Name
transcription.processing
Type
Description
A transcription is currently being processed by transcription servers.
Name
transcription.failed
Type
Description
A transcription failed to be processed.
Name
transcription.processed
Type
Description
A transcription has finished processing and can be consumed.
Name
template.created
Type
Description
A new template was created in our system.
Name
template.updated
Type
Description
A template was updated in our system.
Name
template.ready
Type
Description
A template has finished processing and can be consumed. This event will return the template parsed config that can be used to render the template using the Player.
Name
template.rendered
Type
Description
A template has finished rendering and can be consumed. This event is fired when a video is rendered from a template using the Render Template API.
Name
asset.created
Type
Description
An asset was created in our system.
Name
asset.uploaded
Type
Description
An asset has finished uploading and can be consumed.
Name
asset.processed
Type
Description
An asset has finished processing and can be consumed. This event will return the video metadata.
Name
asset.failed
Type
Description
An asset failed to be processed or uploaded.

Example payload

{
  "id": "X3Jq5j12GN",
  "event": "video.processed",
  "timestamp": 1671238849,
  "webhook_version": 2,
  "metadata": {
    //...
  }
}