The Schedaero API can notify your application when various API resources are created or modified. Your application must have an internet-reachable online endpoint that can receive the webhook messages. A webhook is always set up for a specific company account and will only generate notifications for that company.

Subscribing


Subscribing to notifications for a particular company account is done by calling one of these operations, using an API connection set up for this company

# operation to create a new active webhook

POST /webhooks/settings

# operation to activate an existing, previously deactivated webhook

PUT /webhooks/settings/{id}
Unsubscribing


Unsubscribing to notifications is done by calling this operation

# operation to deactivate a webhook

PUT /webhook/settings/{id}

🚧

Note that 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 web-hooks. The id will be used when the application updates a web-hook. 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 web-hook.

Notification Event Types


A webhook subscribes to one or more types of events. See below for a list of the events supported by the Schedaero API

Applications Used By Multiple Companies


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


  1. 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

  2. There are two options available for the service to be able to determine for which company a notification is received:

    1. The application uses different clientIdentifiers for each company’s webhook

    2. The application uses different targetURIs for each company’s webhook

  3. 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

Notification Delivery

Notification 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

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

Handling The Notification


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. Two types of authentication are supported:

O AUTH


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

Creating Signatures Basic HTTP 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

Payloads

All Schedaero webhooks include a JSON document as the body of the HTTP POST

Notification Body


The payload of a webhook includes, at a minimum, the following information:

  • The type of event that occurred

  • The resource that changed

  • The URI where full details of the resource can be retrieved


Typically, upon receiving a webhook, your application will immediately call the Schedaero API to retrieve updated information about the resource. Your application must use the href provided in the webhook to retrieve additional details about the resource.

Webhooks for specific event types may include additional properties in the payload. Your application must receive any additional properties in a notification without error.

{
       "id": "schedaero-trip-123456789",
       "href": "https://schedaero.avinode.com/api/trips/schedaero-trip-123456789",
       "type": "schedaero-trip"
}

Event Types

📘

See sidebar for specific EventType information


Did this page help you?