# Event Notifications (Webhooks) source: https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-data/event-notifications/index.md Event notifications can be used to create an interactive and valuable experience for users. You can be notified when a change occurs regardless if it is accounts, transactions or payments. These steps will ensure you get the most out of notifications: 1. How to get started using notifications. 2. Notifications you can receive. ## Get started {#get-started} In technical terms, a notification is a webhook. A webhook is when you register a web address that is called when specific events happen. The call is comprised of a JSON body that includes information that provides more detail about the event. The terms "notification" and "webhook" are used interchangeably in our documentation. #### Create a webhook endpoint {#create-a-webhook-endpoint} The first step is to create your own endpoint that can receive a POST call with a JSON body and acknowledge the call. You will need to add a new public path to your web service that can be called from our servers. The web service can now receive webhooks with a payload. This allows you to act on the notifications. #### Acknowledgement of notification {#acknowledgement-of-notification} It is important to acknowledge the notification. To acknowledge that a notification has been received, respond with a 200 HTTP status code within a timeout. All other response codes indicate the event was not received. The timeout is shown in milliseconds in the header `X-Aiia-Timeout`. We will retry the notification attempt 20 times with an exponential backoff strategy starting at 30 seconds. Your endpoint should return a 200 HTTP status before any complex logic is executed that could cause a timeout. #### Structure of JSON payload {#structure-of-json-payload} When you receive a webhook notification, you will receive a JSON payload that provides details. The structure is as follows: ```json { "accountsUpdatedWebhook": { "consentId": "9c59147b-f323-44bc-b8e1-2b37a2b69182", "data": { "changedAccounts": [ { "accountId": "MDQzNzc4YWItMzgwYS00MTNmLWJjYmUtMTk5OWQ5Y2FkY2JifERlbW9CYW5rfFpLUk5VdUVYNHFsd2tYZkRkZ2JEVFFFOGFNUktsUmVteG5TNDJiVVVRVDguYzJlYWZkYzQ0Nzc4", "oldestTransactionChangedAt": null, "transactionsChanged": false }, { "accountId": "ZmExODkyNzEtZjk2NS00ZjVjLTk5ZjktZTQ1Y682zYmMyODM5fFRlc3REYXRhQmFuazF8N2aXM5ZFIzd0gzLWhSNWJhY21nSEZCdy4x", "oldestTransactionChangedAt": "2018-11-06T00:00:00Z", "transactionsChanged": true } ] }, "event": "AccountsUpdated" } } ``` The `paymentUpdatedWebhook` object contains all the information about the notification. The notification tells that a payment has been updated. To view the payment update, request the payment using our [payment](https://api.aiia.eu/preview/index.html#tag/Payouts/paths/~1v2~1accounts~1%7BaccountId%7D~1payments~1%7BpaymentId%7D/get) endpoint. All notification payloads are structured in this way. The most outer object, in this case `paymentUpdatedWebhook`, details the type of notification you have received. The included data varies slightly between different notifications. You can see what has returned for each notification by visiting the [event types](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-data/event-notifications/event-types/index.md) section. #### Register webhook URL {#register-webhook-url} The last step in trying out notifications is to register the URL of the webhook endpoint you have created. This needs to be registered with the APP you have created in our [Developer Portal](https://devportal.openbanking.mastercard.com/). You can add a webhook in the apps page under the section called "Webhook". Ensure that your webhook is configured to use HTTPS with a valid certificate. When you set the address to receive notifications, you are prompted to add a secret. The secret is used to validate that the notification is originating from our service. Read more in the section below. #### Delivery headers {#delivery-headers} A request to your configured webhook URL has several special headers: | **Header** | **Description** | |---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `X-Correlation-Id` | A unique identifier value that is attached to the request. See [Correlation IDs](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-data/advanced-topics/index.md#correlation-ids). | | `X-Aiia-Timeout` | Timeout of request in milliseconds. You must finish the request and answer OK (200) before this timeout. | | `X-Aiia-EventId` | A unique key bound to this webhook. This will not change if the webhook is re-sent (can be used as a idempotency key). | | `X-Aiia-Event` | The type of event that triggered the delivery. | | `X-Aiia-ApiVersion` | Currently set to the static string `2021-11-04`. This will change when we are making non-breaking changes. | | `X-Aiia-TimeStamp` | Set to the current unix timestamp when the webhook was executed. | | `X-Aiia-Signature` | HMAC-SHA256 of `{TimeStamp}|{EventId}|{EventType}|{body}`. See below for more information. | ##### Deprecated headers {#deprecated-headers} | **Header** | **Description** | |--------------------|-----------------------------------------------------------------------------------------------------------------------------| | `X-Viia-Event` | **\[Deprecated\]** The type of event that triggered the delivery. | | `X-Viia-Timeout` | **\[Deprecated\]** Timeout of request in milliseconds. You must finish the request and answer OK (200) before this timeout. | | `X-Viia-Signature` | **\[Deprecated\]** HMAC-SHA256 hash to verify that webhook is sent by our service. See below for more information. | Note: **Name change** The headers are named "Viia" because our platform was created under the name Viia. In the future we will remove the old `X-Viia` headers. #### Security {#security} Our service adds a `X-Aiia-Signature` header which allows the client to verify that webhook is sent by us. This is a C# example on how to generate such a signature: ```csharp // `secret` is the shared secret from the Developer Portal string GenerateSignature(NameValueCollection headers, string body, byte[] secret) { var ts = headers["X-Aiia-TimeStamp"]; var eventId = headers["X-Aiia-EventId"]; var eventType = headers["X-Aiia-Event"]; var textBytes = Encoding.UTF8.GetBytes($"{ts}|{eventId}|{eventType}|{body}"); byte[] hashBytes; using (var hasher = new HMACSHA256(secret)) { hashBytes = hasher.ComputeHash(textBytes); } // Convert hash from "AA-BB-CC-..." to "aabbcc..." return BitConverter.ToString(hashBytes).Replace("-", "").ToLower(); } ``` Read the body as a string. Note that deserialization may alter the order of keys, making the signature wrong. Once you have generated your own signature from the webhook request, compare its value against the `X-Aiia-Signature` header value. If they match, the webhook was *generated* by our service. Our service only sends webhooks over HTTPS. To add additional security after validating the signature: * Check that the request is fresh (`X-Aiia-TimeStamp` should be very close to the current timestamp). * Check that `X-Aiia-EventId` has not already been processed. Note: Do not rely on the source IP for validation, as it may change without notice. ## Event notifications {#event-notifications} Notifications have been added for important events that can happen and that you may want to react to. For information on each notification event type, refer to [event types](https://developer.mastercard.com/open-finance-europe/documentation/unlicensed/aiia-data/event-notifications/event-types/index.md).