--- title: "Configure balance webhooks" description: "Learn how you can configure and receive automatic notifications about the balance changes in your balance platform." url: "https://docs.adyen.com/platforms/balance-updates/configure-balance-webhook" source_url: "https://docs.adyen.com/platforms/balance-updates/configure-balance-webhook.md" canonical: "https://docs.adyen.com/platforms/balance-updates/configure-balance-webhook" last_modified: "2026-05-23T12:56:20+02:00" language: "en" --- # Configure balance webhooks Learn how you can configure and receive automatic notifications about the balance changes in your balance platform. [View source](/platforms/balance-updates/configure-balance-webhook.md) **Limited availability**\ Balance webhooks are in pilot phase. Some of the processes and documentation may change as the feature evolves. *** Adyen can send you webhooks to notify you of balance changes in your balance platform. This can help you avoid [negative balances](/platforms/reconciliation-use-cases/verify-balances/#negative-balances) in your users' balance accounts. To receive these webhooks, you must subscribe to the [Balance webhook](https://docs.adyen.com/api-explorer/balance-webhooks/latest/overview) in your [Customer Area](https://ca-test.adyen.com/). Use the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) to set the conditions that a balance change must meet for Adyen to send a balance webhook: * In your entire balance platform * In the balance accounts of specific account holders * In a specific balance account ## Requirements | Requirement | Description | | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that your [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview) credential has the following role:- **Balance Platform BCL role** | | **[Customer Area roles](/account/user-roles)** | Make sure that you have at least one of the following roles:- **Merchant technical integrator** - **Merchant admin** | | **Limitations** | You can create maximum 20 webhook settings per balance webhook. In each webhook setting, you can configure maximum 20 sets of conditions in the `conditions` array. | ## 1. Subscribe to the balance webhook To receive notifications about balance changes in you balance platform, you must subscribe to the **Balance webhook** in your [Customer Area](https://ca-test.adyen.com/). To subscribe to the balance webhook: 1. Log in to your company account in your [Customer Area](https://ca-test.adyen.com/). 2. Go to **Developers** > **Webhooks**. 3. Select the **Platforms** tab. 4. Select ****Create new webhook**.\ If you have multiple balance platforms, select the one where you want to configure the new webhook. 5. Next to **Balance Webhook**, select **Add**. 6. Under **General**, select the toggle to enable the webhook. You can also provide a description. 7. Under **Server configuration**, enter your webhook server's public URL and select an encryption protocol. 8. Under **Security**, configure the following: | Setting | Description | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Basic authentication** | Enter your server's username and password. We include these details in the header of the webhook to authenticate with your server. | | **HMAC Key** | Select **Generate a new key** to create a hex-encoded HMAC key. You need this key to receive [HMAC signed webhooks](/development-resources/webhooks/configure-and-manage/#validate-hmac). Copy and save the HMAC key securely in your system — you won't be able to copy it later. | 9. Select **Save configuration**. 10. Take note of the ID of the webhook. You need it to configure the webhook settings with the [Configuration API](https://docs.adyen.com/api-explorer/balanceplatform/latest/overview). ## 2. Configure the balance webhook To set conditions when Adyen sends webhooks for balance changes in your balance platform, make a POST [/balancePlatforms/{id}/webhooks/{id}/settings](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings) request, specifying the balance platform ID and the balance webhook ID as path parameters. In the body of the request, include the following parameters: | Parameter | Required | Description | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type of the webhook that you want to configure. Set this to **balance**. | | [target](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-target) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The type and ID of the resource about whose balance changes you want to get notified. | | [target.type](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-target-type) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The resource for which you want to receive webhooks. Possible values:- **balancePlatform**: receive webhooks for balance changes in your entire balance platform. - **accountHolder**: receive webhooks for balance changes for all balance accounts of a specific user. - **balanceAccount**: receive webhooks for balance changes in a specific balance account. | | [target.id](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-target-id) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique identifier of the `target.type`. This can be the ID of your balance platform, your account holder, or a balance account. | | [currency](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-currency) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The currency of the balance for which you want to receive webhooks. | | [status](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-status) | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Specifies the status of the webhook setting. Possible values:- **active**: You receive a balance webhook if any of the conditions in this setting are met. - **inactive**: You do not receive a balance webhook even if the conditions in this settings are met. | | [conditions](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-conditions) | | The array of conditions a balance change must meet for Adyen to send the webhook. To trigger the webhook, the balance change must meet *all* the conditions you set. If you don't specify any conditions, you will receive updates for *all* balance changes in the specified balance account(s). | | [conditions.balanceType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-conditions-balanceType) | | The type of balance for which you want to receive webhooks. Possible values:- **available**: the balance available for use. - **balance**: the sum of transactions that have already been settled. - **pending**: the sum of transactions that will be settled in the future. - **reserved**: the balance currently held in reserve. | | [conditions.conditionType](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-conditions-conditionType) | | Possible values: **greaterThan**, **greaterThanOrEqual**, **lessThan**, **lessThanOrEqual**. | | [conditions.value](https://docs.adyen.com/api-explorer/balanceplatform/latest/post/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings#request-conditions-value) | | The value limit you set for the specified `balanceType` and `currency`. | The following example shows how you can set a balance condition for the balance webhook to get notified when the available balance in your liable balance account drops below USD 5000. **Configure balance webhook setting** ```bash curl https://balanceplatform-api-test.adyen.com/bcl/v2/balancePlatforms \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "type": "balance", "target" : { "type": "balanceAccount", "id": "BA00000000000000000LIABLE" }, "currency": "USD", "status": "active", "conditions": [ { "balanceType": "available", "conditionType": "lessThan", "value": 500000 } ] }' ``` In the response, take note of the `id` of the balance webhook setting. You will need it later if you want to view, modify, or delete the webhook configuration settings, or want to match the webhook event you receive with the setting you're interested in. **Balance webhook setting successfully configured** ```json { "id": "BWHS00000000000000000000000001", "type": "balance", "target": { "type": "balanceAccount", "id": "BA00000000000000000LIABLE" }, "currency": "USD", "status": "active", "conditions": [ { "balanceType": "available", "conditionType": "lessThan", "value": 500000 } ] } ``` When you start receiving webhooks, make sure you [accept each one](/development-resources/webhooks/handle-webhook-events). ## Troubleshooting You may receive errors when setting balance webhook conditions. The following examples show some of the most common issues and how to resolve them. ** #### Duplicated conditions **Error code 1047\_002** ```json { "type": "https://docs.adyen.com/errors/bad-request", "errorCode": "1047_002", "title": "Invalid request content error", "detail": "Duplicated conditions provided.", "requestId": "e23ba7fa86620e34a5f2643703450b96", "status": 400, "invalidFields": [ { "name": "conditions", "value": "[Condition[balanceType=available, conditionType=lessThan, value=500000], Condition[balanceType=available, conditionType=lessThan, value=500000]]", "message": "The conditions of the setting." } ] } ``` #### Solution Make a PATCH [/balancePlatforms/{id}/webhooks/{id}/settings/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings/\(settingId\)) request and change or delete one of the duplicated condition values. ** #### Account not found **Error code 1047\_404** ```json { "type": "https://docs.adyen.com/errors/not-found", "errorCode": "1047_404", "title": "Not found", "detail": "Account not found.", "requestId": "7830854fd16bac465dd2f06545455fa8", "status": 404, "invalidFields": [ { "name": "type", "value": "BalancePlatform", "message": "The target account type." }, { "name": "id", "value": "AdyenBan", "message": "The target account id." } ] } ``` #### Solution 1. Check the ID of the target balance platform, account holder, or balance account included in the response. 2. Resend the POST [/balancePlatforms/{id}/webhooks/{id}/settings/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings/\(settingId\)) request with the correct ID. ** #### Invalid currency provided **Error code 1047\_001** ```json { "type": "https://docs.adyen.com/errors/validation", "errorCode": "1047_001", "title": "Validation error", "detail": "Invalid currency provided.", "requestId": "6f5f850c80706cf8e47f4094b80b6e48", "status": 400, "invalidFields": [ { "name": "currency", "value": "EU", "message": "The currency of the webhook setting." } ] } ``` #### Solution 1. Check the currency code in the response. 2. Resend the POST [/balancePlatforms/{id}/webhooks/{id}/settings/{id}](https://docs.adyen.com/api-explorer/balanceplatform/latest/patch/balancePlatforms/\(balancePlatformId\)/webhooks/\(webhookId\)/settings/\(settingId\)) request with the correct [3-letter ISO currency code](https://en.wikipedia.org/wiki/ISO_4217). ## See also [Use cases](/platforms/balance-updates/use-cases) [See examples of how you can configure the balance webhook for specific use cases.](/platforms/balance-updates/use-cases) [Manage balance webhook settings](/platforms/balance-updates/manage-balance-webhook) [Learn how you can update or delete your balance webhook settings.](/platforms/balance-updates/manage-balance-webhook) [Top up balance accounts](/platforms/top-up-balance-account) [Set up automatic or on-demand direct debits from your user's bank account.](/platforms/top-up-balance-account)