Skip to main content
Optimization Protection

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

  1. You create a webhook subscription using the POST /subscriptions endpoint.
  2. Notifications automatically opts your subscription for verification and prepares a webhook notification with type: subscriptionVerification and subtype: webhookVerification.
    • Ensure that your server accepts webhooks with this type and subtype.
  3. Notifications attempts to deliver the verification webhook to your server using the callbackURL and securityPreferences you 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_VERIFICATION and a merchant servicing case is created.
Attention

A 301 HTTP response (redirect) will result in verification failure. Ensure that you put the exact callbackURL in your subscription.

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"
    }
  }
}
Note

Webhook verification is automatically performed when you update an active subscription's callback URL or security preferences.

Verification status

The following table lists the statuses of a webhook verification and its details:

Webhook verification status
Verification status Description Comments
PENDING_VERIFICATION The verification process is underway.
  • If the subscription remains in PENDING_VERIFICATION status for more than 3 hours, contact the support or integration team.
  • If the subscription is being retried, you can see the details of the previous retries under the verificationAttempts object in the response. 
    • Based on the details of the previous retries, you can choose to update your subscription using the PUT /subscriptions/{subscription-id} endpoint to fix any issues.
  • While the subscription is in this status, you cannot create a new subscription or delete the subscription.
ACTIVATED The verification was successful and your subscription is active.
  • Verification is expected to complete within 2 to 3 hours of subscription creation. 
  • For a subscription to be activated, a 200 or 201 HTTP response is required.
FAILED_VERIFICATION The verification was unsuccessful and your subscription is inactive.

If verification fails for the subscription, try the following:

  • Check if your server accepts a webhook with type: subscriptionVerification and subtype: webhookVerification.
  • Investigate your logs to identify why you are not returning a 200 or 201.
  • Create a new subscription with the correct callbackURL and securityPreferences.

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:

Required header fields
Header name Description
entity-id Unique identifier for the entity.
entity-type

The type of entity identifier. Valid values are:

  • MERCHANT
  • PLATFORM
  • CLIENT
  • ACCOUNT
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
}
Is this page helpful?