Creating a Custom Webhook

Webhooks allow you to integrate SHIFT with any external system, including your own. Webhooks are automated messages sent from SHIFT when something happens. The messages can be sent anywhere you want.

In short, when an event happens in SHIFT we'll send a message to an HTTP endpoint. Then you can do whatever you want with that message.

Get set up

Firstly, when developing webhook integrations is good to have a quick and simple way to view the messages that your webhook integration is receiving. To start consider setting up a Request Bin. This is a fast way to get a server listening to the messages that will be sent from SHIFT. From here you'll be able to see the information you can get back from SHIFT in response to an action taken by one of your team members.

πŸ“˜

You don't need requestbin.

If you're comfortable setting up your own server you can do that instead. We're showing you requestbin in this example in case you might not have the ability to set up your own http server.

When you set up your request bin you should see something like this:

Notice a couple things:

  • The endpoint is shown in large bold letters. You'll need this when creating your webhook in SHIFT.
  • There a button to "SEND TEST EVENT" that allows you to try out sending an example message to your request bin. Give this a try so you can get comfortable with how request bin works.

Creating the webhook

Now, that we have a server listening let's create a webhook. For this example we'll be creating a webhook that responds to "Project Create" events. So, anytime a user creates a new project in SHIFT our webhook should send a new message to our server.

curl --request POST \
  --url https://api.shift.io/v3/webhooks \
  --header 'content-type: application/json' \
  --header 'x-key: YOUR_API_KEY' \
  --header 'x-secret: YOUR_API_SECRET'
  --data '{"eventBinding":"project.create","transport":"http","transportProperties":{"endpoint":"https://c6b334113877ffc7ee98c6339761832c.m.pipedream.net"}}'

πŸ“˜

Notice the endpoint

In the above request notice that the "endpoint" value matches the endpoint from the request bin that we created above.

Now go ahead and create a new project. You should see a message arrive at your request bin endpoint.

Creating project webhooks

You can scope your webhooks to specific projects limiting them from firing for events that occur outside of the project they are configured for. You can do this by adding a "filter" to you webhook. See how the following example scopes the webhook to the project "98b188c2-1e00-4e00-b216-0bbe8e25bc4a".

curl --request POST \
  --url https://api.shift.io/v3/webhooks \
  --header 'content-type: application/json' \
  --header 'x-key: YOUR_API_KEY' \
  --header 'x-secret: YOUR_API_SECRET'
  --data '{"id":"b76438da-892b-44e6-8e4a-fcddc72ff6d3","eventBinding":"asset.create","filter":{"project.id":["98b188c2-1e00-4e00-b216-0bbe8e25bc4a"]},"transport":"http","transportProperties":{"endpoint":"https://c6b334113877ffc7ee98c6339761832c.m.pipedream.net"}}'

Notice how the above example uses the "asset.create" event binding instead of the "project.create" event binding like the previous example. This is because this is a project scoped webhook. Since you can't create a project within a project it wouldn't make sense to create a webhook for "project.create" within a project.

Webhook event bindings

There are several events you can set up webhooks for.

Action

Event Binding

A new project is created

project.create

A project is modified

project.update

A project is deleted

project.delete

An existing user is added to a project

project_users.create

A user is removed from a project

project_users.delete

A new user is invited to a project

project_invitation.create

A new asset is created

asset.create

An asset is modified

asset.update

An asset is deleted

asset.delete

An asset is ingested and ready for playback

asset_source.ready

A link has been created for one or more assets

quicklink.create

A link has been deleted

quicklink.delete


What’s Next
Did this page help you?