Webhooks

An application can use webhooks to subscribe to different kinds of notifications. The application must have an online service that can receive the notifications. A webhook is always set up for a specific company account and will only generate notifications for that company.

Subscribing and Managing Your Webhooks

Create and manage webhook subscriptions for a particular company account by calling one of these operations using an API connection set up for that company:

• POST /webhooks/settings operation to create a new active webhook.
• GET /webhooks/settings operation to list all current webhooks for a company.
• PUT /webhooks/settings/{id} operation to update an existing, previously created webhook.

Unsubscribing

Unsubscribing to notifications is done by calling this operation.

• PUT /webhooks/settings/{id} operation to deactivate the webhook

🚧

Please note

Webhooks are exposed through the Avinode API, and these calls must be made to the Avinode URI for the target environment (e.g. sandbox.avinode.com)

The application creating the web-hook should always store and keep track of all ids of any created webhooks. The id will be used when the application updates a webhook. As mentioned above, for example the action of inactivating or reactivating or changing any of the other settings; the PUT /webhooks/settings/{id} operation is used for updating a webhook.

Notification Specifics

Notification Event Types

A webhook subscribes to one or more types of events. See the specific pages related to Avinode Webhooks and Schedaero Webhooks for a list of the events supported by each API.

Delivery

When the webhook is triggered by an event, a notification will be delivered to the application’s online service. The notification is a JSON message sent in an HTTPS POST call to the URL specified in the webhook settings. The API servers will repeatedly try to deliver the notification to the application’s service until the notification has been consumed successfully. However, if the service has not successfully consumed it after 48 hours, the API servers will stop trying to deliver it.

Payload Format

The consuming service must be able to handle that additional JSON properties can be added at any time. Existing JSON properties will however not be changed. More detailed information about the payload format can be found on each notification category page.

Consuming the Notification

To report that the notification has been successfully consumed, the service must reply with an HTTP 200 code. The service should consume the call as quickly as possible. If the notification delivery times out before the remote system has responded, the notification will be considered undelivered and it will be rescheduled for delivery at a later time. So ideally, the service consuming the notification will just save it and immediately end the call by responding with an HTTP 200 code. The service consuming notifications must also be designed to be able to consume multiple parallel notification calls.
After the notification has been consumed, the application can execute any business logic to handle the notification.

Authentication

It is recommend that the service is set up to authenticate the incoming notification calls. The following types of authentication are supported:

OAuth

An OAuth key and OAuth secret is set up in the webhook settings. From these an OAuth signature is generated sent along with each notification call. The method used to generate the OAuth signature is described on this page.

https://dev.twitter.com/oauth/overview/creating-signatures

Basic Authentication

A username and password is set up in the webhook settings. These are formatted according to the Basic HTTP Authentication method, and once the server responds with a 401 Unauthorized, they are sent with the subsequent notification call in the Authorization header.

Preemptive Basic Authentication

A username and password is set up in the webhook settings. These are formatted according to the Basic HTTP Authentication method and sent along with each notification call in the Authorization header.

Applications Used By Multiple Companies

Applications handling webhook notifications for multiple company accounts need to be able to handle multiple webhooks and the notifications generated by these. Here are the recommended best practices:

• Each company using the application should be able to specify their own API connection by entering its authorization token. The application will use this API connection when creating and updating webhooks for this company
• There are two options available for the service to be able to determine for which company a notification is received:
  -The application uses different clientIdentifiers for each company’s webhook
  -The application uses different targetURIs for each company’s webhook
• When the application has determined for which company a notification has been received, it will use this company’s API connection in any API calls made while handling the notification