Webhook structure and types

When you configure a webhook, Adyen offers different webhook types to choose from. Each webhook type has its own corresponding events that you can subscribe to. For example, the Standard webhook type subscribes your endpoint to a set of default event types. This page provides you with a list of webhook types, and which event types Adyen offers for each.

There are two main categories of webhooks:

• Payments webhooks
• Platforms webhooks

Event types

Every webhook message contains an event type. The event type lets your server know what kind of information a webhook message contains. The event types your server receives depends on which webhooks you configured in your Customer area. For example, if you configure a Configuration webhook, you will receive webhook messages with its corresponding event types.

Use the event type to inform the business logic in your system. For example, if you receive a webhook message with an eventCode of CAPTURED, you can update your order management system and start the shipping process.

The event type is indicated by different fields, depending on the webhook type.

• In Payments webhooks, the event type is typically in the eventCode field.
• In Platforms webhooks, the event type is typically in the type field.

Payments webhooks

Payments webhook structure

Each payments webhook payload contains the following fields.

• live: Specifies whether the event happened on the test or live environment.
• notificationItems: An array of NotificationRequestItem objects.

  JSON and HTTP POST webhooks contain only one NotificationRequestItem object in the notificationItems array. SOAP webhooks may contain up to six NotificationRequestItem objects, in case the events happen within a very short period of time.

The notificationItems object contains information about the event:

• additionalData: Additional information about the shopper or the transaction. For more information about the fields that you can receive in additionalData, refer to Additional settings.
• eventCode: The event type.
• success: The outcome of the event, set to either true or false.

  For some event codes, such as REPORT_AVAILABLE, the success field is always set to true.

• eventDate: The time of the event. Format: ISO 8601; YYYY-MM-DDThh:mm:ssTZD

Some fields included in the NotificationRequestItem object depend on the type of event triggered. For example, webhook events triggered by a request to refund a payment include:

• originalReference: The pspReference of the original payment.

Standard webhooks

For most payment integrations, you need to sign up for Standard webhooks. Standard webhooks have default and non-default event types that you subscribe to when you configure the webhook.

Default event types

Adyen sends the Standard webhook with default event types that cannot be disabled.

Because we sometimes create new webhooks and event types, you should set up your server to be able to accept webhooks of more types and receive more event type values than are listed below. When we create a new event type, you have to create new business logic if you want to use it.

By default, the Standard webhook includes the following eventCode values. There are different categories of event codes:

• Transaction events
• Dispute events
• Payout events

Transaction events

Dispute events

For more information and examples, refer to Dispute webhooks.

Payout events

For more information and examples, refer to Payout webhooks.

Non-default event codes

There are additional event codes that are not enabled in the Standard webhook by default. You can enable them:

• On the Standard webhook page
• On the Webhooks settings page
• On the Risk settings page

On the Standard webhook page

1. In your Customer Area, select Developers > Webhooks.

2. From the list of webhooks, select the Standard webhook to configure.

3. From the Webhook details panel, select the Edit webhook icon .

4. On the Standard webhook page, in the Events row, select the Edit icon .

5. From the list, select the checkboxes for the event codes you want to enable:

   eventCode	Description
   OFFER_CLOSED	The offer has expired, for example, because the shopper abandoned the session. For cards, offers expire after 12 hours by default.
   RECURRING_CONTRACT	A recurring contract has been created, and the shopper's payment details have been stored with Adyen. The recurringDetailReference is included in the pspReference field. You must also enable this event code on the Webhooks settings page. To get updates related to tokens, we recommend to use the new Recurring tokens life cycle events webhook instead.

6. Select Apply.

7. Select Save.

On the Webhooks settings page

You can enable the following eventCode values in the Webhook settings page.

1. In your Customer Area, go to Developers > Webhooks.

2. Select Settings.

3. On the Webhooks settings page, select the checkboxes for the event code you want to enable:

   eventCode	Description
   RECURRING_CONTRACT	A recurring contract has been created, and the shopper's payment details have been stored with Adyen. The recurringDetailReference is included in the pspReference field. You must also enable this event code on the Standard webhook page. To get updates related to tokens, we recommend to use the new Recurring tokens life cycle events webhook instead.
   POSTPONED_REFUND	The refund for the payment will be performed after the payment is captured.
   AUTHENTICATION	An authentication-only flow was performed.
   CAPTURE	Receive CAPTURE webhook events if you are using delayed automatic capture. You must also enable this event code on the Standard webhook page.

4. Select Save

On the Risk settings page

Follow instructions to configure case management webhook events to enable these eventCode values:

Other webhooks

In addition to Standard webhooks, you can get other types of webhooks:

1. Set up a separate endpoint to receive the type of webhook. Each endpoint that you set up can receive only one type of webhook.
2. Add the webhook type you want to receive.

Platforms webhooks

Platforms webhook structure

Each Platforms webhook payload contains the following fields:

• data: An object containing the event-specific data. The structure of this object depends on the type of the event.
• environment: Specifies whether the event happened on the test or live environment.
• timestamp: The time of the event, in ISO 8601 format.
• type: The event type. For a list of possible values, refer to the tables of event types for Platforms webhooks.

{
    "data": {
        "balancePlatform": "YOUR_BALANCE_PLATFORM",
        "accountHolder": {
            "legalEntityId": "LE00000000000000000001",
            "reference": "YOUR_REFERENCE-2412C"
        }
    },
    "environment": "live",
    "timestamp": "2024-12-15T15:42:03+01:00",
    "type": "balancePlatform.accountHolder.updated"
}

Authentication webhook

Use Authentication webhooks to get the outcome of 3D Secure authentications for payment instruments in your Adyen Issuing integration. To learn more, see Authenticate cardholders.

Balance Webhook

Use Balance webhooks to monitor balances of users on your platform. This webhook is useful for Adyen for Platforms, Issuing, and Business Accounts integrations to manage funds. For example, you can automate topping up a balance account when its funds are low, or receive a notification for a negative balance. Learn more at Track balance updates.

Capital grant webhook

Use Capital grant webhooks to get updates about grants in your Adyen Capital integration.

Capital offer webhook

Card Order webhook

Use Card Order webhooks to track the lifecycle of physical card orders in your Adyen Issuing integration.

Configuration webhook

Configuration webhooks are essential for Adyen for Platforms and integrations that use Adyen's Financial products. These webhook events inform you about the creation and updates of resources, like account holders, balance accounts, payment instruments, and sweeps. Your integration needs configuration webhooks to track the status of users as you onboard and verify them.

Dispute webhook

Use Dispute webhooks to track the dispute lifecycle for cards created with Adyen Issuing. When you raise a dispute, Adyen sends webhooks to inform you about its creation and outcome.

Negative Balance Compensation Warning Webhook

Get a warning when a balance account on your platform has a negative balance for an extended period. This webhook is useful for Adyen for Platforms, Issuing, and Business Accounts integrations to manage financial risk. It informs you before an automatic deduction is made from your liable account, giving you an opportunity to settle the negative balance with your user.

Network token webhook

Use network token webhooks to track the status of network tokens for cards created with Adyen Issuing. These webhook events are important if you want to know when a user adds their card to a digital wallet like Apple Pay or Google Pay. To learn more, see Manage network tokens.

Onboarding on invite

Use Onboarding on invite webhooks to get a notification when a user is successfully onboarded to your platform. This webhook is part of an Adyen for Platforms integration in the Onboarding on invite flow.

Report webhook

Use this webhook to automate your reporting and reconciliation processes for Balance Platform reports. For example, receive a notification when your Balance Platform Accounting Report is available for download.

Transaction webhook

Use Transaction webhooks to get track the fund movement of transfers on your platform. This webhook is important for Adyen for Platforms, Issuing, Capital, and Business Accounts integrations. It informs you when a transfer is booked, for example, when an outgoing external transfer is completed.

Transfer webhook

Use transfer webhooks to track lifecycle of fund movements on your platform, from initiation to completion. This webhook is important for Adyen for Platforms, Issuing, Capital, and Business Accounts integrations. It is especially important for tracking the state payouts, for example.

See also