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.
    • If we receive a 200 or 201 HTTP response, your subscription is ACTIVATED.
    • If verification fails, 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:

Json
{
  "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 status of a webhook verification can be one of the following:

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.
  • While any subscription is in this status, no subscription operations (POST, PUT, DELETE, etc) can be performed.
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 /pendingSubscriptions/{request-id} using your subscription’s request ID.

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.

The following is a sample code block of retrieving a webhook verification:

HTTP method: GET
Endpoint: /pendingSubscriptions/{request-id}

Json
{
  "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"
}

Subscribe to notifications