Subscribe to notifications

post/createNotificationConfiguration

API Version

Creates a subscription to notifications informing you of events on your platform. After the subscription is created, the events specified in the configuration will be sent to the URL specified in the configuration. Subscriptions must be configured on a per-event basis (as opposed to, for example, a per-account holder basis), so all event notifications of a marketplace and of a given type will be sent to the same endpoint(s). A marketplace may have multiple endpoints if desired; an event notification may be sent to as many or as few different endpoints as configured.

Endpoint destination URL

https://cal-test.adyen.com/cal/services/Notification/v6/createNotificationConfiguration

Request Parameters

Required

Optional

Details of the prospective notification subscription configuration.

Indicates whether the notification subscription is active.

The version of the notification to which you are subscribing. To make sure that your integration can properly process the notification, subscribe to the same version as the API that you're using.

A description of the notification subscription configuration.

Contains objects that define event types and their subscription settings.

A string with which to salt the notification(s) before hashing. If this field is provided, a hash value will be included under the notification header HmacSignature and the hash protocol will be included under the notification header Protocol. A notification body along with its hmacSignatureKey and Protocol can be used to calculate a hash value; matching this hash value with the HmacSignature will ensure that the notification body has not been tampered with or corrupted.

Must be a 32-byte hex-encoded string (i.e. a string containing 64 hexadecimal characters; e.g. "b0ea55c2fe60d4d1d605e9c385e0e7f7e6cafbb939ce07010f31a327a0871f27").

The omission of this field will preclude the provision of the HmacSignature and Protocol headers in notification(s).

Adyen-generated ID for the entry, returned in the response when you create a notification configuration. Required when updating an existing configuration using /updateNotificationConfiguration.

The password to use when accessing the notifyURL with the specified username.

The URL to which the notifications are to be sent.

The username to use when accessing the notifyURL.

The SSL protocol employed by the endpoint.

Permitted values: TLSv12, TLSv13.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
configurationDetailsobject
Details of the notification subscription configuration.
activeboolean
Indicates whether the notification subscription is active.
apiVersioninteger
The version of the notification to which you are subscribing. To make sure that your integration can properly process the notification, subscribe to the same version as the API that you're using.
descriptionstring
A description of the notification subscription configuration.
eventConfigsarray[object]
Contains objects that define event types and their subscription settings.
eventTypestring
The type of event.

Possible values: ACCOUNT_CLOSED, ACCOUNT_CREATED, ACCOUNT_FUNDS_BELOW_THRESHOLD, ACCOUNT_HOLDER_CREATED, ACCOUNT_HOLDER_LIMIT_REACHED, ACCOUNT_HOLDER_PAYOUT, ACCOUNT_HOLDER_STATUS_CHANGE, ACCOUNT_HOLDER_STORE_STATUS_CHANGE, ACCOUNT_HOLDER_UPCOMING_DEADLINE, ACCOUNT_HOLDER_UPDATED, ACCOUNT_HOLDER_VERIFICATION, ACCOUNT_UPDATED, BENEFICIARY_SETUP, COMPENSATE_NEGATIVE_BALANCE, DIRECT_DEBIT_INITIATED, PAYMENT_FAILURE, REFUND_FUNDS_TRANSFER, REPORT_AVAILABLE, SCHEDULED_REFUNDS, TRANSFER_FUNDS.
includeModestring
Indicates whether the specified eventType is sent to your webhook endpoint. Possible values:

INCLUDE: Send the specified eventType.

EXCLUDE: Send all event types except the specified eventType and other event types with the includeMode set to EXCLUDE.

hmacSignatureKeystring
A string with which to salt the notification(s) before hashing. If this field is provided, a hash value will be included under the notification header HmacSignature and the hash protocol will be included under the notification header Protocol. A notification body along with its hmacSignatureKey and Protocol can be used to calculate a hash value; matching this hash value with the HmacSignature will ensure that the notification body has not been tampered with or corrupted.

Must be a 32-byte hex-encoded string (i.e. a string containing 64 hexadecimal characters; e.g. "b0ea55c2fe60d4d1d605e9c385e0e7f7e6cafbb939ce07010f31a327a0871f27").

The omission of this field will preclude the provision of the HmacSignature and Protocol headers in notification(s).
notificationIdinteger
Adyen-generated ID for the entry, returned in the response when you create a notification configuration. Required when updating an existing configuration using /updateNotificationConfiguration.
notifyPasswordstring
The password to use when accessing the notifyURL with the specified username.
notifyURLstring
The URL to which the notifications are to be sent.
notifyUsernamestring
The username to use when accessing the notifyURL.
sslProtocolstring
The SSL protocol employed by the endpoint.

Permitted values: TLSv12, TLSv13.

invalidFieldsarray[object]
Contains field validation errors that would prevent requests from being processed.
errorCodeinteger
The validation error code.
errorDescriptionstring
A description of the validation error.
fieldTypeobject
The type of error field.
fieldstring
The full name of the property.
fieldNamestring
The type of the field.
shareholderCodestring
The code of the shareholder that the field belongs to. If empty, the field belongs to an account holder.
pspReferencestring
The reference of a request. Can be used to uniquely identify the request.
resultCodestring
The result code.
400 - Bad Request
A problem reading or understanding the request.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
401 - Unauthorized
Authentication required.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
403 - Forbidden
Insufficient permissions to process the request.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
422 - Unprocessable Entity
A request validation error.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
500 - Internal Server Error
The server could not process the request.
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.

Subscribe to notifications

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error