Web-hooks and notifications

Web-hooks

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

Subscribing and managing your web-hooks

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

Unsubscribing

Unsubscribing to notifications is done by calling this operation.

Notification specifics

Delivery

When the web-hook 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 web-hook 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 web-hook 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 web-hook 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 web-hook settings. These are formatted according to the Basic HTTP Authentication method and sent along with each notification call in the Authorization header.

Notification categories

A web-hook subscribes to one or many notification categories. For each category, different types of notifications can be sent. See API reference POST /webhooks/settings page for details on how to subscribe to each type of notification.

Trip Request

If an operator subscribes to this notification category, the operator will receive a notification each time a broker (buyer) has sent a new trip request to the operator or an existing one has been updated.

Notifications of this type are sent when:

  • A new RFQ has been created for the operator.
  • An existing RFQ has been updated with additional information, like another lift added.
  • An existing RFQ has been canceled by the broker.

After this notification has been consumed, the application can download the RFQ information as described in the Operator download RFQ use case. The application should always use the URL provided in the notification payload when downloading the RFQ.

{
  "id": "arfq-12345678",
  "href": "https://sandbox.avinode.com/api/rfqs/arfq-12345678",
  "type": "rfqs"
}

Trip Chat - Buyer

If an operator subscribes to this notification category, the operator will receive a notification each time a broker (buyer) has sent a new chat message to the operator.

Notifications of this type are sent when:

  • A broker (buyer) has sent a new chat message
{
    "id": "abuyermsg-1000000023",
    "href": "https://sandbox.avinode.com/api/tripmsgs/abuyermsg-1000000023",
    "type": "tripmsgs"
}

Trip Request - Seller Response

If a broker subscribes to this notification category, the broker will receive a notification each time an operator has replied to an RFQ.

Notifications of this type are sent when:

  • An operator (seller) has submitted a quote.
  • An operator (seller) has declined an RFQ.

After this notification has been consumed, the application can download the trip message information by calling the GET /tripmsgs/{id} operation. The application should always use the URL provided in the notification payload when downloading the information.

{
  "id": "asellermsg-12345678",
  "href": "https://sandbox.avinode.com/api/tripmsgs/asellermsg-1234567",
  "type": "tripmsgs"
}

Trip Chat - Seller

If a broker subscribes to this notification category, the broker will receive a notification each time an operator has sent a new chat message to the broker.

Notifications of this type are sent when:

  • An operator (seller) has sent a new chat message associated with an RFQ.

After this notification has been consumed, the application can download the trip message information by calling the GET /tripmsgs/{id} operation. The application should always use the URL provided in the notification payload when downloading the information.

{
    "id": "asellermsg-1000000007",
    "href": "https://sandbox.avinode.com/api/tripmsgs/asellermsg-1000000007",
    "type": "tripmsgs"
}

Trip Request (My Company)

If an operator or broker subscribes to this notification category, they will receive a notification each time they themselves have sent some kind of communication to the other party.

Notifications of this type are sent when:

  • Someone in your company sends a trip request
  • Someone in your company cancels a trip request

After this notification has been consumed, the application can download the trip message information by calling the GET /tripmsgs/{id} operation. The application should always use the URL provided in the notification payload when downloading the information.

{
    "id": "arfq-1000000017",
    "href": "https://sandbox.avinode.com/api/rfqs/arfq-1000000017",
    "type": "rfqs"
}

Trip Request - Seller Response (My Company)

If an operator (seller) subscribes to this notification category, they will receive a notification each time they themselves have sent some kind of communication to the broker.

Notifications of this type are sent when:

  • Someone in your company submits a quote to a trip request
  • Someone in your company declines a trip request

After this notification has been consumed, the application can download the trip message information by calling the GET /tripmsgs/{id} operation. The application should always use the URL provided in the notification payload when downloading the information.

{
    "id": "asellermsg-1000000008",
    "href": "https://sandbox.avinode.com/api/tripmsgs/asellermsg-1000000008",
    "type": "tripmsgs"
}

Trip Chat (My Company)

When subscribing to this notification category, a notification will be sent each time someone in your company chats on a trip. It could be as an operator (seller) or as a broker (buyer).

After this notification has been consumed, the application can download the trip message information by calling the GET /tripmsgs/{id} operation. The application should always use the URL provided in the notification payload when downloading the information.

{
    "id": "asellermsg-1000000008",
    "href": "https://sandbox.avinode.com/api/tripmsgs/asellermsg-1000000008",
    "type": "tripmsgs"
}

or

{
    "id": "abuyermsg-1000000023",
    "href": "https://sandbox.avinode.com/api/tripmsgs/abuyermsg-1000000023",
    "type": "tripmsgs"
}

Empty Legs

When subscribing to this notification category, a notification will be sent each time an empty leg, matching a watch configuration (empty leg subscription), is created, updated, or deleted.

Notifications of this type are sent for empty legs matching any of the empty leg watches set up for the company.

The following events will trigger a notification:

  • A new empty leg is published in the Avinode Marketplace.
  • An empty leg previously published in the Avinode Marketplace is updated.
  • An empty leg is unpublished from the Avinode Marketplace.

After this notification has been consumed, the GET /emptylegs/{id} operation can be called to get the empty leg details. The application should always use the URL provided in the notification payload when getting the empty leg details.
The operation will return a HTTP 404 if the empty leg has been unpublished by the operator.

{
  "id":"el-123456789",
  "href":"https://services.avinode.com/api/emptylegs/el-123456789",
  "type":"emptylegs"
}

Client Leads

When subscribing to this notification category, a notification will be sent each time there is a new client lead sent into Avinode. This could be originating from an Avinode web app or a custom end-client facing app using the POST /leads operation.

After this notification has been consumed, the GET /leads/{id} operation can be called to get the client lead details. The application should always use the URL provided in the notification payload when getting the client lead details.

{
  "id": "ecl-1000000017",
  "href": "https://sandbox.avinode.com/api/leads/ecl-1000000017",
  "type": "leads"
}

Applications used by multiple companies

Applications handling web-hook notifications for multiple company accounts needs to be able to handle multiple web-hooks 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 web-hooks 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 client identifiers for each company’s web-hook.
    • The application uses different target URIs for each company’s web-hook.
  • 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.

👍

Implementation checklist

All items on this check list must be true in order for an application to be allowed to subscribe to and consume web-hook notifications from the live environment.

  • When a web-hook notification is received, the service will return its response as quickly as possible.
  • The application should always use the URL provided in the notification payload when downloading the information.
  • The service can consume and handle multiple parallel, and even potentially identical, web-hook notifications.
  • The application does not break if a previously unknown notification type is received.
  • The application must be able to handle that additional JSON properties can be added to notification messages at any time.

Did this page help you?