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 |
| String | The ISO 8601 timestamp of when the change occurred |
| String | The type of event that this notification refers to. Possible options are:
|
| Object | A Data object that describes the change being notified. This object's content varies based on the |
DATA_CHANGE
notifications
DATA_CHANGE
notificationsNotifications 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
The Data object in these notifications contains the following properties:
Property | Type | Description |
| String | The type of data object that the change affects. Possible options are:
|
| String | The AID of the entity affected by this change. |
FLIGHT_UPDATE
notifications
FLIGHT_UPDATE
notificationsNotifications 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
The Data object in these notifications contains the following properties
Property | Type | Description |
---|---|---|
| String | This is currently a static value always set to |
| 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. |
| String | The API URL to retrieve full information about the flight. |
| String | Describe the action that the flight has executed and that is being notified. Options currently implemented are:
Options reserved but not currently implemented are:
|
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
signed_payload
stringThe 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.
Last updated