Webhooks - for automations with freispace

Use Cases

Webhooks allow other third-party applications to be notified in real time whenever a change occurs within freispace.

In addition to sending a notification to the third-party, a payload containing all event-related data is sent, allowing for automations.

Examples

A few ways you can use webhooks include:

• Create notifications in your preferred application when an event occurs.
  • If a project information changes.
  • If a booking changes.
  • When a new project is created.
• Trigger automations on your server or computers.
  • Prepare server space for a new project.
  • Copy project files to the correct editing suite where the edit is going to happen.
• Triggering other applications to respond to an event.

How it works

The notification URL must do the following:

• Expect JSON data from a POST request and respond with a 2xx HTTP status code to freispace as soon as possible to acknowledge the successful receipt of the event notification. If your application fails to acknowledge the notification in a timely manner, a duplicate event is sent that your application.

Applications need at least one reachable notification URL to receive and process webhook events from freispace. Notification URLs are specified on the Integrations page of your team settings.

For a list of all freispace API events that you can subscribe to, see Webhook Events Reference.

How to set up your webhook integration

To start receiving webhook events in your application, create and register a webhook endpoint by following the steps below. You can register and create one endpoint to handle several different event types at once, or set up individual endpoints for specific events.

1. Identify which events you want to monitor.
2. Develop a webhook endpoint function to receive event data POST requests.
3. Register your endpoint within freispace.
4. Secure your webhook endpoint.

Requirements and limitations

The notification URL must do the following:

• Respond with a 2xx HTTP status code to freispace within 10 seconds to acknowledge the receipt of the event notification.

• The URL endpoint must require that a connection uses HTTPS.

• You must properly set up the webhook event subscription on the integrations page of your team settings.

freispace can not guarantee a timely delivery of notifications:

• In most cases, event notifications arrive in well under 60 seconds of the associated event.

• There's no guarantee of the delivery order of event notices.

Mode of Operation

freispace allows you to notify URL endpoints when specified events happen. The endpoints will be notified asynchronously.

Signed Requests

All requests are signed with HMAC using the sha256 algorithm. The secret will be provided during setup.

Failed Webhooks

When the receiving end fails to send a response with a 2xx HTTP status code, we will will consider the call as failed. Failed webhooks will be retried a maximum of two additional times, with a timeout in order to avoid too many calls in a short amount of time.