Webhook structure and types

Learn which webhook types are sent for each event.

Each webhook payload contains an eventCode that specifies the type of event triggered. Some eventCodes are enabled in Standard webhooks by default, and some need to be enabled.

In addition to the Standard webhook, you can also receive other types of webhooks.

Webhook structure

Each webhook event 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 type of event. For a list of possible eventCode values, refer to Event codes.
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.

For more information about the fields included in specific webhook events, refer to Event codes.

Event codes

Adyen sends the Standard webhook with Default event codes that cannot be disabled. You can also enable additional non-default event codes.

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

Default event codes

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

`eventCode`	Description
AUTHORISATION	The `success` field informs you of the outcome of a payment request. For payment methods that return an immediate authorisation result, such as cards, you will also receive an AUTHORISED webhook event. Although you can use the payment result from the API, we recommend that you rely on the webhook to trigger any business logic to make sure that your system is able to handle both synchronous and asynchronous payment flows.
AUTHORISATION_ADJUSTMENT	The `success` field informs you of the outcome of a request to adjust the authorised amount. The `originalReference` field contains the `pspReference` of the original payment.
CANCELLATION	The `success` field informs you of the outcome of a request to cancel a payment. The `originalReference` field contains the `pspReference` of the original payment.
CANCEL_OR_REFUND	The `success` field informs you of the outcome of a request to cancel or refund a payment. The `originalReference` field contains the `pspReference` of the original payment.
CAPTURE	The `success` field informs you of the outcome of a request to capture a payment. The `originalReference` field contains the `pspReference` of the original payment. By default, the CAPTURE webhook is not sent for automatic captures. If you are using delayed automatic capture, you must also enable this event code on the Webhooks settings page.
CAPTURE_FAILED	The capture failed due to rejection by the card scheme. The `originalReference` field contains the `pspReference` of the original payment. Technical failures are automatically re-captured by Adyen within 10 business days. You can simulate this webhook event by following our guide on testing failed modifications.
`EXPIRE`	The original payment has expired on the Adyen payments platform. The `success` field is always true because the payment expired on the Adyen payments platform. The `amount` field contains the details of the original payment. For more information, refer to Expiration of authorizations.
`HANDLED_EXTERNALLY`	The payment has been handled outside the Adyen payments platform.
ORDER_OPENED	Sent when the first payment for your payment request is a partial payment, and an order has been created.
ORDER_CLOSED	The `success` field informs you of the outcome of the shopper's last payment when paying for an order in partial payments. Possible values: true: The full amount has been paid. false: The shopper did not pay the full amount within the `sessionValidity`. All partial payments that were processed previously are automatically cancelled or refunded.
REFUND	The `success` field informs you of the outcome of a request to refund a payment. The `originalReference` field contains the `pspReference` of the original payment. Possible values: true: The refund request was successful. false: The refund request failed due to a technical issue
REFUND_FAILED	The refund failed due to a rejection by the card scheme. The `originalReference` field contains the `pspReference` of the original payment. You can simulate this webhook event by following our guide on testing failed modifications.
REFUNDED_REVERSED	The refunded amount has been returned to Adyen, and is back in your account. The `originalReference` field contains the `pspReference` of the original payment. For more information, refer to Failed refund.
REFUND_WITH_DATA	The `success` field informs you of the outcome of a request to refund with data.
REPORT_AVAILABLE	A new report is available. The `reason` field contains the URL where you can download the report, and the `pspReference` field contains the name of the report.
VOID_PENDING_REFUND	The `success` field informs you of the outcome of a request to cancel an unreferenced POS refund. The `originalReference` field contains the `pspReference` of the original payment.

You won't receive a webhook event when a payment is settled.

Dispute events

`eventCode`	Description
CHARGEBACK	A payment was charged back, and the funds were deducted from your account.
CHARGEBACK_REVERSED	A chargeback has been defended towards the issuing bank. This stage is not final. If the issuing bank decides to present a second chargeback, you might still lose the chargeback case.
NOTIFICATION_OF_CHARGEBACK	The dispute process has opened. You should investigate the dispute and supply defense documents.
NOTIFICATION_OF_FRAUD	The alert passed on by issuers to schemes and subsequently to processors. Visa calls them TC40 and Mastercard calls them System to Avoid Fraud Effectively (SAFE). These are informational webhook events offered at no charge by Adyen, providing you the opportunity to take action, such as blocking a shopper or issuing a refund before a chargeback is incurred.
PREARBITRATION_LOST	Your pre-arbitration case has been declined by the cardholder's bank.
PREARBITRATION_WON	Your pre-arbitration case has been accepted by the cardholder's bank.
REQUEST_FOR_INFORMATION	A shopper has opened an RFI (Request for Information) case with the bank. You should supply defense documents to help shopper understand the charge.
SECOND_CHARGEBACK	The issuing bank declined the material submitted during defense of the original chargeback. The disputed amount is deducted from your account.

For more information and examples, refer to Dispute webhooks.

Payout events

`eventCode`	Description
PAYOUT_EXPIRE	The payout has expired.
PAYOUT_DECLINE	The user reviewing the payout declined it.
PAYOUT_THIRDPARTY	The `success` field informs you of the outcome of a payout request: true: The request was successful. false: The request failed. The `reason` field contains a short description of the problem.
PAIDOUT_REVERSED	The financial institution rejected the payout. We will return the funds back to your account. The `reason` field contains the bank statement description if present.

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

In your Customer Area, select Developers > Webhooks.
From the list of webhooks, select the Standard webhook to configure.
From the Webhook details panel, select the Edit webhook icon .
On the Standard webhook page, in the Events row, select the Edit icon .

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.

Select Apply.
Select Save.

On the Webhooks settings page

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

In your Customer Area, go to Developers > Webhooks.
Select Settings.

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.
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.

Select Save

On the Risk settings page

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

`eventCode`	Description
MANUAL_REVIEW_ACCEPT	The manual review triggered by risk rules was accepted.
MANUAL_REVIEW_REJECT	The manual review triggered by risk rules was rejected.

Other webhooks

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

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

Webhook type	Description
Account data webhook	Receive a webhook event when a merchant account was created, or if the capabilities of a merchant account were updated.
Account settings details	Receive a webhook event when there is a status change related to your company account, merchant account, or store. This webhook is not available by default, and it has a different format. Refer to Account settings webhooks.
ACH Notification of Change webhook	Receive a webhook event when you sent an ACH Direct Debit transaction and Adyen has received a notification that the customer's bank account details have changed.
Adyen Giving merchant webhook	Receive a webhook event with `eventCode`: DONATION when a shopper has made a donation.
BankTransfer pending webhook	Receive a webhook event with `eventCode`: PENDING when there is a pending bank transfer payment.
Boleto Bancario pending webhook	Receive a webhook event with `eventCode`: PENDING when there is a pending Boleto Bancario payment.
Direct-debit pending webhook	Receive a webhook event with `eventCode`: PENDING when there is a pending direct debit payment.
Generic pending webhook	Receive a webhook event with `eventCode`: PENDING when there is a pending payment for any redirect payment method.
Ideal details	Receive AUTHORISATION webhook event for iDEAL payments, with the following shopper details included in the `additionalData` object: `iDealConsumerAccountNumber` `iDealConsumerIBAN` `iDealConsumerBIC` `iDealConsumerName` `iDealConsumerCity` `iDealTransactionId`
Ideal pending	Receive a webhook event with `eventCode`: PENDING when there is a pending iDEAL payment.
OXXO pending webhook	Receive a webhook event with `eventCode`: PENDING when there is a pending OXXO voucher payment.
Payment method webhook	Receive a webhook event when a payment method was successfully configured or when the configuration failed.
Terminal assignment complete	Receive a webhook event when a scheduled assignment of a payment terminal has been completed. Refer to Use API calls to assign terminals.
Terminal boarding succeeded	Receive a webhook event when the boarding of a terminal succeeded.
Terminal settings updated	Receive a webhook event when the terminal settings are updated. Refer to Configure terminal settings.
Terminal order update	Receive a webhook event about updates to your sales, return, or replacement order for payment terminals. Refer to Order or return terminals.

Webhook structure and types