Notification webhooks

Configure webhooks to receive and accept notifications from the Balance Platform.

The Balance Platform sends notifications to communicate events such as payments and fund transfers. You receive these notifications through webhooks.

Since many of the events on the Balance Platform are asynchronous, handling webhooks is required for a successful integration.

The Balance Platform notifications return a different JSON object from the Adyen payments notification. If you want to reuse an existing endpoint, make sure the endpoint is able to handle the new notification structure.

To process webhooks from the Balance Platform, you need to:

Expose a webhook endpoint on your server.
Accept notifications.

Step 1. Configure a webhook endpoint

You will need to expose an endpoint that:

Can receive a JSON object.
Has an open TCP port for HTTPS traffic on port 443, 8443, or 8843.
Can handle basic authentication.

Once you have an endpoint ready, reach out to your Adyen contact to configure the endpoint within the Adyen platform. We will provide a shared secret that you will use to validate HMAC signatures.

Step 2: Accept notifications

To ensure that your server is properly accepting notifications, we require you to acknowledge every notification of any type with an [accepted] response.

If we don't receive this response within 10 seconds, for example because your server is down, all notifications to your endpoint will be queued and retried.

When your server receives a webhook:

Verify the HMAC signature included in the notification.
This is to confirm that the notification was sent by Adyen, and was not modified during transmission.
Store the notification in your database.
Acknowledge the notification with the following response:
```
[accepted]
```

Notification example

All notifications in the Balance Platform are about payments or fund transfers.

You can determine the notification by the type, such as balancePlatform.payment.created.

Here is an example notification for an authorised payment:

https://docs.adyen.com/issuing/notification-webhooks#payment-authorisation-webhook

Payment notification

{
   "data" : {
      "accountHolder" : {
         "description" : "S.Hopper - Staff 123",
         "id" : "AHA1B2C3D4E5F6G7H8I9J0"
      },
      "{hint:Amount converted to the default currency code}amount{/hint}" : {
         "currency" : "EUR",
         "value" : -88
      },
      "authCode" : "245773",
      "balanceAccount" : {
         "description" : "S.Hopper - Main balance account",
         "id" : "BAB8B2C3D4E5F6G7H8D9J6GD4"
      },
      "balancePlatform" : "YOUR_BALANCE_PLATFORM_ACCOUNT",
      "creationDate" : "2020-08-16T21:10:32+02:00",
      "{hint:The payment ID}id{/hint}" : "3UHFB75NIZPDCWN0",
      "merchantData" : {
         "mcc" : "7999",
         "merchantId" : "526567789010068",
         "nameLocation" : {
            "city" : "Amsterdam",
            "country" : "NLD",
            "name" : "NB Bookstore",
            "rawData" : "NB Bookstore Amsterdam NLD"
         }
      },
      "{hint:Original value and currency of the payment}originalAmount{/hint}" : {
         "currency" : "USD",
         "value" : -100
      },
      "paymentInstrument" : {
         "id" : "PI322FN2235HGP5BNR47LCX2D"
      },
      "relayedAuthorisationData" : {
         "metadata" : {
            "key1" : "value1",
            "key2" : "value2"
         },
         "reference" : "1594926632477"
      },
      "{hint:The result of the payment}status{/hint}" : "Authorised",
      "validationResult" : [
         {
            "result" : "valid",
            "type" : "PaymentInstrumentExpirationCheck"
         },
         {
            "result" : "valid",
            "type" : "RelayedAuthorisation"
         },
         {
            "result" : "valid",
            "type" : "CVC2"
         },
         {
            "result" : "valid",
            "type" : "TransactionRules"
         },
         {
            "result" : "valid",
            "type" : "ExchangeAmount"
         },
         {
            "result" : "valid",
            "type" : "Validation"
         },
         {
            "result" : "valid",
            "type" : "TransactionValidation"
         },
         {
            "result" : "valid",
            "type" : "Screening"
         },
         {
            "result" : "valid",
            "type" : "MaxAuthAmount"
         }
      ]
   },
   "environment" : "test",
   "type" : "balancePlatform.payment.created"
}