canonical: https://jentic.com/apis/adyen.com/adyen-management-notification-service-v1 # Adyen Management Webhooks Specification for the webhook payloads Adyen sends when configuration changes happen across company and merchant accounts, stores, payment terminals, and payment methods that are managed via the Management API. Adyen makes HTTP POST requests to the merchant's configured webhook URL with the event payload as the body, and the merchant's server authenticates the request using HTTP Basic credentials. This spec describes the payload contracts so receivers can validate and parse incoming events. ## For AI agents Reference for the webhook payloads Adyen sends when merchant accounts, stores, payment terminals, and payment methods change via the Management API. ## Scope Does not handle outbound API calls or transaction-level events - use for receiving and parsing Adyen Management configuration webhooks only. ## Capabilities - Describe payload schemas for merchant-account-level events such as creation, updates, and verification status changes - Describe payload schemas for payment-method-level events tied to a merchant account - Describe payload schemas for terminal management events covering boarding, assignment, and settings - Authenticate inbound webhook calls using HTTP Basic credentials configured on the receiver - Provide the contract a receiver needs to validate signatures and idempotently process events ## Use cases ### Configuration Drift Detection Subscribe a receiver to Adyen Management webhooks to detect drift between the merchant's source-of-truth configuration store and the live Adyen settings. Each event arrives as an HTTP POST with a typed payload describing what changed (account, store, terminal, payment method). The receiver parses the event, compares it to its source-of-truth, and raises an alert when a change was made directly in the Customer Area without going through the platform's automation. Example prompt: Configure a receiver endpoint with HTTP Basic auth, parse the inbound event payload using the spec, and write the change to the configuration_audit table for drift comparison ### Terminal Estate Monitoring Track payment terminal lifecycle events across the estate by listening for terminal boarding, settings, and assignment webhooks. The Management Webhooks spec documents the payload of each event so the receiver can identify the affected terminal and update an inventory or monitoring dashboard. Useful for retailers operating large fleets of POS terminals across multiple stores. Example prompt: Listen for terminal boarding events, look up the affected terminalId in the inventory table, and update its status to active once the boarding event is received ### AI Agent Configuration Awareness AI agents that configure Adyen merchant accounts through the Management API can subscribe to Management Webhooks via Jentic to confirm that configuration calls succeed asynchronously. The agent uses Jentic to wire up the webhook receiver schema, parses inbound events, and updates its internal state. Credentials for outbound Management API calls remain isolated in your Jentic One instance while the receiver authenticates inbound webhooks with HTTP Basic credentials of its own. Example prompt: Use Jentic to call the Management API to update a merchant account, then listen for the corresponding Management Webhook event payload to confirm the change propagated ## Key resources - **Merchant Account Events** — Payloads for events tied to merchant accounts (creation, updates, status changes) - **Payment Method Events** — Payloads for events tied to enabling, disabling, or updating payment methods - **Terminal Management Events** — Payloads for terminal boarding, assignment, and settings updates ## Why Jentic - **Setup:** Wiring Adyen Management webhooks by hand means creating subscriptions with an X-API-Key and validating inbound calls with a separate HTTP Basic credential. Through Jentic you install once, import the Management webhooks from the API Directory, store both credentials once, and your agent handles subscriptions and payloads. - **Permission scoping:** These are inbound configuration 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 parsing a merchant account event. Because you pick the operations, the agent only handles the event types you include. - **Credential handling:** Your Adyen X-API-Key for subscriptions and the HTTP Basic credential for inbound receivers are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'subscribe to adyen management webhooks' or 'parse a merchant account event', and Jentic returns the matching Management webhook operation with its receiver payload schema so the agent handles the right type without browsing the reference docs. ## Related APIs - **Adyen Management API** — The outbound API whose configuration changes trigger Management Webhook events - **Adyen Classic Platforms Notifications** — Webhook payloads for the classic for-platforms integration - **Stripe API** — Stripe Events deliver similar account configuration change notifications ## FAQ ### What authentication does Adyen Management Webhooks use? Adyen authenticates inbound calls to your webhook URL with HTTP Basic credentials that you configure when you create the webhook subscription in the Customer Area or via the Management API. Your receiver should reject requests that do not present the configured username and password. Through Jentic, the credentials used to subscribe to webhooks via the Management API are stored encrypted in your Jentic One instance. ### How are Management Webhooks different from notifications about payments? Management Webhooks cover configuration changes (merchant accounts, payment methods, terminals, stores), not transaction events. Payment-level events such as authorisations, captures, and refunds are delivered through Adyen's Standard Notifications. Subscribe to both if you need a complete picture of platform and transaction activity. ### What are the rate limits for receiving Management Webhooks? Adyen does not apply rate limits to outbound webhooks the way it does to inbound API calls, but your receiver must respond with HTTP 200 within Adyen's timeout (a few seconds). If your receiver responds with non-2xx codes or times out, Adyen retries with backoff. Long-running processing should be queued asynchronously after the 200 response. ### How do I subscribe to Management Webhooks through Jentic? Use Jentic to call the Adyen Management API's webhook subscription endpoints, which create the subscription pointing at your receiver URL. Search Jentic for 'create Adyen management webhook' to find the matching Management API operation. Once subscribed, your receiver parses the payloads using this spec. Run it through Jentic One, the self-hosted execution layer. ### Are Management Webhook payloads signed? Adyen supports HMAC signature validation on webhooks when you configure an HMAC key on the subscription. The signature is delivered in the request headers and the receiver must recompute it from the raw payload to verify authenticity. The Management Webhooks spec describes the payload structure that goes into the signature computation. ### Can I limit what my agent is allowed to do with the Adyen Management Webhooks? Yes. Because Jentic One is self-hosted, you decide which of these inbound configuration event schemas your agent may handle, so you can allow it to parse merchant account events while excluding payment method or terminal management events it does not need. Since these are event payload contracts rather than outbound calls, the agent only processes the event types you choose to include. The HTTP Basic credential your receiver uses to authenticate inbound calls is stored encrypted by your own Jentic One instance and injected at execution time, never entering the agent's prompt or logs.