Webhook

The webhook object is passed using the POST REST verb to an URL indicated by the User, to notify a customer's system about events happening in the aviowiki data.

Events represent changes in data, and some information is given to assist the receiving service to select the best course of action to be taken.

The POST requests include a JSON Body and a digital signature in the Header.

A webhook notification is made up of a root Notification object and of a Data object, which contains details about the specific notification being sent.

Notification object

The Notification object is the root object of the JSON passed in the Body of the POST request sent to the webhook.

Its properties are:

Property	Type	Description
timestamp	String	The ISO 8601 timestamp of when the change occurred
event	String	The type of event that this notification refers to. Possible options are: DATA_CHANGE for changes in all static datasets. For more information refer to Data Changes Notifications. FLIGHT_UPDATE for events detected during a flight. For more information refer to Flight Update Notifications.
data	Object	A Data object that describes the change being notified. This object's content varies based on the event type. For full details refer to the following paragraphs.

DATA_CHANGE notifications

Notifications with event DATA_CHANGE alert the client about changes in a static dataset, like a new airport being published, or a change in a runway length.

An example of a DATA_CHANGE notification is shown below

{
  "timestamp": "2021-05-24T15:27:04",
  "event": "DATA_CHANGE",
  "data": {
    "type": "AIRPORT",
    "aid": "APT-1234-ABCD",
    "action": "EDIT",
    "url": "https://api.aviowiki.com/airports/APT-1234-ABCD"
  }
}

The Data object in these notifications contains the following properties:

Property	Type	Description
type	String	The type of data object that the change affects. Possible options are: AIRPORT AIRPORT_AVAILABILITY RUNWAY PROVIDER PROVIDER_AVAILABILTY REGION AIRPORT_NOTES COUNTRY_NOTES PROVIDER_PRODUCT FUEL_PRODUCT FUEL_COST AIRPORT_AUTHORITY AIRPORT_AUTHORITY_CONTACT COUNTRY_AUTHORITY COUNTRY_AUTHORITY_CONTACT
aid	String	The AID of the entity affected by this change.

FLIGHT_UPDATE notifications

Notifications with event FLIGHT_UPDATE alert the client about changes in the status of an aircraft moving. This data is computed by aviowiki using flight tracking data based on Mode-S, ADS-B and ADS-C messages.

As an example, the body of such notification would look similar to the below

{
  "event": "FLIGHT_UPDATE",
  "timestamp": "2022-05-27T09:39:55.501951673",
  "data": {
    "type": "FLIGHT",
    "url": "https://api.aviowiki.com/flights/88bc0cf1-4480-4d4a-b121-136f442e8dfa",
    "id": "88bc0cf1-4480-4d4a-b121-136f442e8dfa",
    "action": "LANDING"
  }
}

The Data object in these notifications contains the following properties

Property	Type	Description
type	String	This is currently a static value always set to FLIGHT to indicate that the notification relates to a flight status change.
id	String	The unique id of the flight. This is in UUID Version 4 format. A flight is created when the first event is detected by aviowiki.
url	String	The API URL to retrieve full information about the flight.
action	String	Describe the action that the flight has executed and that is being notified. Options currently implemented are: TAKE_OFF to indicate the lift-off. LANDING to indicate the touch-down Options reserved but not currently implemented are: OFF_BLOCK ON_BLOCK APPROACH OFF_ROUTE RETURN_TO_STAND INITIATE_EMERGENCY END_EMERGENCY DIVERSION

Security

Webhook notifications are served over a TLS connection to the endpoint specified when creating the subscription. To make sure that webhooks are correctly delivered, please make sure that your client is capable of TLS version 1.2 or above, and that the connection is secure by a trusted certificate (you can obtain one for free from Let's Encrypt).

Because most of the content of a web request can be spoofed, all our webhooks are served with a Header that contains a digital signature of the content. When you create a new webhook subscription, you are provided with a secret string, which is the private key used to generate such signatures.

The header containing the signature is called aviowiki-signature and it looks something like this:

t=1637657904997,v1=f2f04243c4794a9c359691c8a88d4c8681d128184647af2e0bf4133b90d05322

As you can see the header is divided into two parts: t and v1. t contains a timestamp, while the v1 parameter is the HMAC signature of the request body.

To verify the signature, you should follow the steps below.

Step 1: Extract the timestamp and signatures from the header

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and v1 corresponds to the signature. You can discard all other elements.

Step 2: Prepare the signed_payload string

The signed_payload string is created by concatenating:

• The timestamp (as a string)

• The character .

• The actual JSON payload (i.e., the request body)

Step 3: Determine the expected signature

Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload string as the message.

Step 4: Compare the signatures

Compare the signature in the header to the expected signature. For an equality match, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.

To protect against timing attacks, use a constant-time string comparison to compare the expected signature to the received signature.