# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

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

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

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

## Related

[Subscribe to notifications](/docs/commerce/optimization-protection/capabilities/notifications/how-to/subscribe-notifications)