V4 Webhooks

What’s a Webhook?

A webhook is a push-style HTTP callback that Frame.io fires as soon as something interesting happens in your account (e.g., a new file finishes transcoding, a comment is added, a project is created). Instead of polling the API, you supply a public HTTPS URL; Frame.io sends a JSON payload to that URL in real time so you can:

For more on what a webhook is, and what it does, see https://docs.webhook.site/.

Endpoint Overview

Updates to Webhooks in Frame V4

Webhook Event Subscriptions

When creating and updating webhooks identify which events you’re interested in. Choose as few or as many as you’d like, note that the experience is better if you subscribe to fewer events, splitting up your webhooks logically with different naming schemes and different endpoints so that you can model your business logic on the receiving end to do less filtering and routing in shared functions.

Projects

Files

Folders

Comments

Metadata

Collections

Custom Fields

Shares

Webhook Message Payload

All webhook payloads contain a type field, indicating the type of event that triggered a webhook, as well as a resource object. The resource object specifies the type and ID of the resource related to this event.

Example Payload

1
{
2
  "account": {
3
    "id": "6f70f1bd-7e89-4a7e-b4d3-7e576585a181"
4
  },
5
  "project": {
6
    "id": "7e46e495-4444-4555-8649-bee4d391a997"
7
  },
8
  "resource": {
9
    "id": "d3075547-4e64-45f0-ad12-d075660eddd2",
10
    "type": "file"
11
  },
12
  "type": "file.ready",
13
  "user": {
14
    "id": "56556a3f-859f-4b38-b6c6-e8625b5da8a5"
15
  },
16
  "workspace": {
17
    "id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
18
  }
19
}

In the above example of an file.created event, the resource.id indicates the id of the newly created Asset. Additionally, workspace, project, and user objects are included. These resource identifiers indicate the team.id, project.id and user.id of the resource that the webhook relates to, and can be used to filter events on the receiving end of the incoming webhook without having to resort to making an API call to look up the resource. If you’ve implemented any sort of caching of those resources, you can also perform a local look up against your cache without resorting an additional API call.

Security

By default, all webhooks have a signing key. This non-configurable signing secret can be used to verify that the request originates from Frame.io.

The response payload for the webhook you’ve configured includes the signing secret specific to this webhook. This secret is only provided in this initial webhook create response, so store it somewhere safe in your secrets storage or environment variables. Use it later to verify the webhook is coming directly from our servers and was not intercepted or manipulated in any way.

Verifying Webhook Signatures

To guard an integration against man-in-the-middle and replay attacks it is essential to verify the signature of the webhook payload. Verification ensures that webhook payloads were actually sent by Frame.io and payload content has not been modified in transport.

Included with the POST request are the following HTTP headers:

1
import hmac
2
import hashlib
3
4
def verify_signature(curr_time, req_time, signature, body, secret):
5
    """
6
    Verify Webhook signature
7
    :Args:
8
        curr_time (float): Current epoch time
9
        req_time (float): Request epoch time
10
        signature (str): Signature provided by the Frame.io API for the given request
11
        body (str): Webhook body from the received POST
12
        secret (str): The secret for this Webhook that you saved when you first created it
13
    """
14
    if int(curr_time) - int(req_time) < 500:
15
        message = 'v0:{}:{}'.format(req_time, body)
16
        calculated_signature = 'v0={}'.format(hmac.new(
17
            bytes(secret, 'latin-1'),
18
            msg=bytes(message, 'latin-1'),
19
            digestmod=hashlib.sha256).hexdigest())
20
        if calculated_signature == signature:
21
            return True
22
    return False

The timestamp is the system time from Frame.io’s systems when the outbound webhook is sent. This can be used to prevent replay attacks. We recommended verifying this time is within 5 minutes of local time.

The signature is a HMAC SHA256 hash using the signing key provided when the Webhook is first created.

Follow these steps to verify the signature:

Retries and Logging

Changes to Webhooks

Webhooks created in Legacy transfer to V4 with the following changes.

Webhook Tutorial

Step 1: Setup receiving end (done first so that you know what your URL will be)

Here, we’re using webhook.site which allows you to easily spin up a single-use webhook receiver that can be used for inspecting payloads, sending basic responses without any actual business logic. When you first navigate to https://webhook.site, a unique webhook endpoint is created for you which you can copy right away to use.

This URL is unique to your session.

Step 2: Choose the event(s) you want to subscribe to

For this tutorial, we’ll keep it simple and setup this webhook to just subscribe to file.created events. The JSON payload we’ll use for the webhook creation will be as follows.

1
{
2
    "data": {
3
        "name": "asset.created sample webhook",
4
        "events": ["file.created"],
5
        "url": "https://webhook.site/c05f2216-9558-4816-bc09-f77ee7b9de40"
6
    }
7
}

Step 3: Create a webhook resource using Postman

Using Postman, make an API call to create the webhook resource, supplying the webhook.site endpoint in the payload.

Step 4: Test!

Now that you’ve created the webhook subscription and have an endpoints setup to receive webhooks, it’s time to test it out by triggering the first webhook by performing the appropriate action that would cause it to fire!

Since our sample was set up to trigger on the file.created trigger, we’ll go ahead and upload a new asset into any Project within the corresponding Account and Workspace that the webhook was set up in.

Additional Resources