canonical: https://jentic.com/apis/adyen.com/adyen-configuration-webhooks # Adyen Configuration webhooks Adyen Balance Platform Configuration Webhooks notify your server of changes to account holders, balance accounts, payment instruments, card orders, and sweeps inside an Adyen for Platforms balance platform. The OpenAPI document defines the webhook event payloads - including balancePlatform.accountHolder.created, balanceAccount.updated, paymentInstrument.created, cardorder.created, and balanceAccountSweep events - that Adyen POSTs to your registered endpoint. You implement the receiver; this spec gives you typed schemas for parsing the events. ## For AI agents Receive and parse Adyen Balance Platform configuration events for account holders, balance accounts, payment instruments, card orders, and sweeps. ## Scope Does not handle outbound REST calls, transfer events, or report events - use for inbound balance platform configuration event schemas only. ## Capabilities - Parse balancePlatform.accountHolder.created and accountHolder.updated events to track KYC and capability changes - Handle balanceAccount.created and balanceAccount.updated events to keep ledger state in sync with Adyen - Process paymentInstrument.created and paymentInstrument.updated events for cards and bank accounts issued on the platform - React to balanceAccountSweep.created, updated, and deleted events to monitor automated sweep configurations - Validate incoming notifications using HTTP basic auth credentials configured in the Adyen Customer Area ## Use cases ### Keep an Internal Ledger in Sync with Adyen Balance Platform Platforms running Adyen for Platforms need their internal ledger to mirror Adyen's truth - when Adyen creates or updates an account holder, balance account, or payment instrument, the platform must reflect the change immediately. The Configuration webhooks deliver typed events for every such mutation, so the platform's webhook handler can update its database within seconds of the change in Adyen. Example prompt: Parse an incoming balancePlatform.accountHolder.updated event, extract the accountHolderId and capability state, and update the corresponding row in the platform's internal ledger ### Monitor Card and Payment Instrument Lifecycle Issuers using Adyen for Platforms need to know when a card is issued, activated, or has its status changed. The paymentInstrument and cardorder events fire on every change, letting an operations system trigger downstream actions - sending a card-shipped email, enabling a wallet provision, or alerting fraud when a card status flips unexpectedly. Example prompt: On a balancePlatform.cardorder.updated event with status=delivered, send a card-arrived notification to the cardholder using the linked customer record ### React to Sweep Configuration Changes Automated sweeps move funds between balance accounts on a schedule or trigger. When a sweep is created, modified, or deleted, treasury teams need to know - both for audit and to confirm that a programmatic change took effect. The balanceAccountSweep events expose the full sweep configuration so a treasury system can log the change and re-validate its expectations. Example prompt: On a balancePlatform.balanceAccountSweep.deleted event, write an audit log entry with the sweepId, balanceAccountId, and the previous schedule ### Agent-Driven Webhook Triage via Jentic An ops agent that owns Adyen events can use Jentic to load the typed Configuration webhook schemas and validate, route, and react to incoming notifications without hand-rolling parsers. The agent searches Jentic for the event type, loads the schema definition, and uses it to validate the inbound JSON before deciding which downstream action to take. Example prompt: Use Jentic to load the AccountHolderNotificationRequest schema, validate the inbound webhook body against it, and route the event to the platform's account-holder service ## Key resources - **Account holder events** — balancePlatform.accountHolder.created and updated - **Balance account events** — balancePlatform.balanceAccount.created and updated - **Payment instrument events** — balancePlatform.paymentInstrument.created and updated - **Card order events** — balancePlatform.cardorder.created and updated - **Sweep events** — balancePlatform.balanceAccountSweep.created, updated, and deleted ## Why Jentic - **Setup:** Wiring Adyen Configuration webhooks by hand means validating inbound calls with basic auth and parsing raw notification JSON against the right event type. Through Jentic you install once, import the Configuration webhooks from the API Directory, store the basic auth credential once, and your agent validates payloads against typed schemas. - **Permission scoping:** These are inbound event schemas rather than outbound calls with a resource id in the URL, so you limit the agent to the operations it needs, such as validating an account-holder-created event. Because you pick the operations, the agent only parses the event types you include. - **Credential handling:** The basic auth credential Adyen uses to call your webhook is stored once, encrypted, by your own Jentic One instance and injected at validation time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'account holder created webhook', and Jentic returns the matching Configuration webhook event with its NotificationRequest schema so the agent validates the payload against the right type without browsing the reference docs. ## Related APIs - **Adyen Balance Platform Configuration API** — The REST API that mutates account holders and balance accounts - webhooks notify you of those mutations - **Adyen Transfer webhooks** — Sister webhook spec covering balance platform transfer events - **Stripe** — Stripe Connect issues equivalent webhook events for connected account and issuing changes ## FAQ ### What authentication does the Configuration webhooks use? Adyen authenticates outbound webhook calls to your server using HTTP basic auth with credentials you configure in the Adyen Customer Area. Your receiving endpoint must validate the username/password before trusting the payload. Through Jentic, those validation credentials sit in your Jentic One instance rather than in your handler code. ### Why does the Configuration webhooks spec list zero endpoints? This is an OpenAPI 3.1 webhooks document - Adyen calls your server, not the other way around. The spec defines the webhook event payloads (balancePlatform.accountHolder.created and similar) under the webhooks block, plus the request and response schemas under components. You build the receiver; the spec gives you the typed schemas. ### Which events does the Configuration webhooks fire? Eleven event types covering account holder create/update, balance account create/update, balance account sweep create/update/delete, card order create/update, and payment instrument create/update. Each event delivers a typed NotificationRequest payload defined in the spec. ### How do I acknowledge a Configuration webhook? Respond with a 200 OK and a BalancePlatformNotificationResponse body containing notificationResponse: '[accepted]'. Adyen retries non-2xx responses, so use the typed response schema and return the accepted token only after your handler has durably stored the event. ### How do I parse a Configuration webhook through Jentic? Search Jentic for the relevant Adyen event (for example 'account holder created webhook'), load the AccountHolderNotificationRequest schema from the spec, and validate the inbound webhook body against it before dispatching to your handler logic. ### Can I limit what my agent is allowed to do with the Adyen Configuration Webhooks? Yes. Because you run your own self-hosted Jentic One instance, your own rules decide which of these inbound event schemas the agent may parse, so you can allow it to validate only account-holder-created events while excluding balance account, payment instrument, card order, or sweep events. Since these are typed notification schemas rather than outbound calls, scoping is a matter of the operations you include, and the agent can only validate the event types you have granted it. The basic auth credential Adyen uses to reach your endpoint is injected at validation time and never enters the agent's prompt or context.