Webhook verification
The Notification API automatically verifies that it can deliver notifications to the callback URL you provide when you subscribe to a webhook notification.
How webhook verification works
- You create a webhook subscription using the
POST /subscriptionsendpoint. - Notifications automatically opts your subscription for verification and prepares a webhook notification with type:
subscriptionVerificationand subtype:webhookVerification.- Ensure that your server accepts webhooks with this type and subtype.
- Notifications attempts to deliver the verification webhook to your server using the
callbackURLandsecurityPreferencesyou provided, up to a maximum of 5 automatic retries.- If we receive a 200 or 201 HTTP response, your subscription is
ACTIVATED. - If the verification process is underway or the verification is being retried, the subscription status updates to
PENDING_VERIFICATION. Verification is automatically retried up to five times. - If the verification fails after 5 retries, the subscription status updates to
FAILED_VERIFICATIONand a merchant servicing case is created.
- If we receive a 200 or 201 HTTP response, your subscription is
The following is a sample of the verification webhook you would receive during the verification process:
{
"notificationId": "2bf2b445-60c0-4535-9225-5decd6100c7f",
"platformId": "",
"notificationType": "SubscriptionVerification",
"notificationSubType": "WebhookVerification",
"notificationDescription": "Notification for validating webhook URL for subscriptionId: a7d703ca-38bd-4795-91cf-fd521105c145",
"messageCreateTimestamp": "2026-06-08T19:52:01.139Z",
"subscriptionId": "a7d703ca-38bd-4795-91cf-fd521105c145",
"subscriptionVerification": {
"webhookVerification": {
"subscriptionCreatedTimestamp": "2026-06-08T19:52:01.139Z",
"requestId": "68305209-3e02-4a0b-b60c-49b02e6e148f"
}
}
}Verification status
The following table lists the statuses of a webhook verification and its details:
| Verification status | Description | Comments |
|---|---|---|
PENDING_VERIFICATION |
The verification process is underway. |
|
ACTIVATED |
The verification was successful and your subscription is active. |
|
FAILED_VERIFICATION |
The verification was unsuccessful and your subscription is inactive. |
If verification fails for the subscription, try the following:
|
Retrieve the status of a webhook verification
You can retrieve the verification status by performing a GET request to /subscriptions/verifications/{id} using your subscription’s request ID as the path parameter.
The following table lists the required header fields:
| Header name | Description |
|---|---|
entity-id |
Unique identifier for the entity. |
entity-type |
The type of entity identifier. Valid values are:
|
request-id |
A unique identifier provided by the requestor for each request. |
Scenarios
The following scenarios show sample response code blocks for each verification status.
Activated
The following sample code block shows a scenario in which verification succeeds and your subscription is in ACTIVATED status.
HTTP method: GET
Endpoint: /subscriptions/verifications/{id}
{
"notifications": {
"disputeNotification": [
"DisputeClosed"
]
},
"subscriptionId": "c766945b-e703-4ed1-9e4e-a8ca17caa34e",
"subscriptionCreateTimestamp": "2026-05-18T12:46:33.802Z",
"subscriptionUpdatedTimestamp": "2026-05-18T12:46:47.994Z",
"callbackURL": "https://merchant.notification.com",
"responseStatus": "SUCCESS",
"responseCode": "ACCEPTED",
"responseMessage": "Request Accepted",
"subscriptionChannels": [
"WEBHOOK"
],
"subscriptionStatus": "ACTIVATED"
}Pending verification
The following sample code block shows a scenario in which verification is being retried and your subscription is in PENDING_VERIFICATION status.
HTTP method: GET
Endpoint: /subscriptions/verifications/{id}
{
"notifications": {
"disputeNotification": [
"All"
]
},
"subscriptionId": "73a612cb-4056-4e98-885f-8a1b1a7954c2",
"subscriptionCreateTimestamp": "2026-10-22T11:13:22.426Z",
"subscriptionUpdatedTimestamp": "2026-10-22T11:13:22.954Z",
"callbackURL": "https://merchant.notification.com",
"subscriptionChannels": [
"WEBHOOK"
],
"subscriptionStatus": "PENDING_VERIFICATION",
"verificationAttempts": [
{
"verificationRetryCount": 1,
"callbackResponseCode": "503",
"callbackResponseDescription": "Service Temporarily Unavailable",
"callbackTokenEndpointResponseCode": "503",
"callbackTokenEndpointResponseDescription": "Service Temporarily Unavailable"
}
],
"nextVerificationRetryTimestamp": "2026-10-22T11:28:22.954Z",
"remainingVerificationRetryCount": 4
}Failed verification
The following sample code block shows a scenario in which verification failed after 5 retries and your subscription is in FAILED_VERIFICATIONstatus.
HTTP method: GET
Endpoint: /subscriptions/verifications/{id}
{
"notifications": {
"disputeNotification": [
"All"
]
},
"subscriptionId": "73a612cb-4056-4e98-885f-8a1b1a7954c2",
"subscriptionCreateTimestamp": "2026-10-22T11:13:22.426Z",
"subscriptionUpdatedTimestamp": "2026-10-22T11:49:44.807Z",
"callbackURL": "https://merchant.notification.com",
"subscriptionChannels": [
"WEBHOOK"
],
"subscriptionStatus": "FAILED_VERIFICATION",
"verificationAttempts": [
{
"verificationRetryCount": 1,
"callbackResponseCode": "503",
"callbackResponseDescription": "Service Temporarily Unavailable",
"callbackTokenEndpointResponseCode": "503",
"callbackTokenEndpointResponseDescription": "Service Temporarily Unavailable"
},
{
"verificationRetryCount": 2,
"callbackResponseCode": "503",
"callbackResponseDescription": "Service Unavailable",
"callbackTokenEndpointResponseCode": "503",
"callbackTokenEndpointResponseDescription": "Service Unavailable"
},
{
"verificationRetryCount": 3,
"callbackResponseCode": "503",
"callbackResponseDescription": "Service Temporarily Unavailable",
"callbackTokenEndpointResponseCode": "503",
"callbackTokenEndpointResponseDescription": "Service Temporarily Unavailable"
},
{
"verificationRetryCount": 4,
"callbackResponseCode": "503",
"callbackResponseDescription": "Service Temporarily Unavailable",
"callbackTokenEndpointResponseCode": "503",
"callbackTokenEndpointResponseDescription": "Service Temporarily Unavailable"
},
{
"verificationRetryCount": 5,
"callbackResponseCode": "503",
"callbackResponseDescription": "Service Temporarily Unavailable",
"callbackTokenEndpointResponseCode": "503",
"callbackTokenEndpointResponseDescription": "Service Temporarily Unavailable"
}
],
"remainingVerificationRetryCount": 0
}