Comment on page
The webhook object is passed using the
POSTREST 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.
The Notification object is the root object of the JSON passed in the Body of the
POSTrequest sent to the webhook.
Its properties are:
DATA_CHANGEalert 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_CHANGEnotification is shown below
The Data object in these notifications contains the following properties:
FLIGHT_UPDATEalert 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
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
secretstring, which is the private key used to generate such signatures.
The header containing the signature is called
aviowiki-signatureand it looks something like this:
As you can see the header is divided into two parts:
tcontains a timestamp, while the
v1parameter is the HMAC signature of the request body.
To verify the signature, you should follow the steps below.
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
tcorresponds to the timestamp, and
v1corresponds to the signature. You can discard all other elements.
signed_payloadstring is created by concatenating:
- The timestamp (as a string)
- The character
- The actual JSON payload (i.e., the request body)
Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing
secretas the key, and use the
signed_payloadstring as the message.
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.