# 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` | 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:

| | `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:

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](https://letsencrypt.org/)). 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.aviowiki.com/data-models/webhook.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.