Webhooks

Webhooks let you get notified when events happen in Connect.

Webhooks is a Pro feature.

This feature is currently in Public Beta. Feedback? Mail us at [email protected].

Webhooks let you subscribe to events in Connect. When an event occurs, Connect sends a notification to your webhook endpoint that includes a JSON payload with the updated entity. You can use webhooks in several ways:

  • Notify your colleagues when a transfer has finished

  • Enrich your media asset management system (MAM) with transfer status

  • Start downstream processing when files have been processed or transferred

Getting started

  1. In your back end, create a webhook endpoint handler to receive POST requests with event data.

  2. Log in to Connect using your email or license key

  3. Register your webhook endpoint

  4. Securing your endpoint

1. Create a handler

Set up an HTTP or HTTPS endpoint function that can accept webhook requests with a POST method. If you’re still developing your endpoint, you can use something like Hootdeck CLI to forward the webhook requests to your local development server (see local development).

  1. Handles POST requests with a JSON payload consisting of an event object.

  2. Quickly returns a successful status code (2xx) prior to any complex logic that might cause a timeout.

You can use services like Zapier to create webhooks handlers, and connect that to other systems.

2. Log into Connect

Head on over to the Connect login page with the email address or license key. Webhooks are only available for events originating from computers using a Pro license.

3. Register your secure webhook endpoint

After testing your webhook endpoint function and logging into Connect, you can now register your webhook endpoint’s accessible URL so Connect knows where to deliver events.

To create a new webhook endpoint in the Dashboard:

  1. Open the settings modal by clicking the Settings button at the top

  2. Fill in your full webhook endpoint URL and hit the Save button

4. Securing your endpoint

Coming soon.

Testing with local environments

Webhooks require public-facing URLs. If you're developing locally, you can expose your local development server to the internet using a service like Hookdeck CLI:

  1. Install Hookdeck CLI.

  2. Run your local server. Note the port your local server is running on.

  3. Run hookdeck listen {PORT} connect --path {WEBHOOK_ENDPOINT_PATH}, where {PORT} is the port where your local server is running and {WEBHOOK_ENDPOINT_PATH} is the path to your webhook handler. For example: 

    $ hookdeck listen 3000 connect --path /api/webhook

  4. Use the unique URL generated by Hookdeck CLI as your webhook endpoint URL when registering a webhook endpoint.

Event Delivery behaviours

This section helps you understand different behaviours to expect regarding how Connect sends events to your webhook endpoint.

Respond to events

The server that you set to receive events from Connect should respond with an HTTP 200 status code within three seconds. This lets Connect know that you successfully received the message.

We can't guarantee the order of delivery for webhooks. They may be delivered in a different order to the order they're generated.

Automatic retries

Connect attempts to deliver events to your destination up to three times with an exponential backoff. Connect will retry three times, with a 10-second delay between the first and second attempts, and a 100-second delay for the third attempt.

Last updated