Create Webhook Subscription
This section describes how to create a webhook subscription. The request you send is dependent on your system's security policy. You can subscribe to multiple webhook products and event types in the same request. After creating a subscription, you receive a notification every time your subscribed events occur.
Every webhooks integration uses mutual trust. In addition to mutual trust, you can also use the OAuth or OAuth with JWT security policy. If you are not using OAuth security to authenticate your webhook notifications, use the default mutual trust request.
Endpoints
Send a POST request to one of these endpoints:
POST /notification-subscriptions/v2/webhooks
POST /notification-subscriptions/v2/webhooks
POST /notification-subscriptions/v2/webhooks
Security Policy Methods
The required fields and the request body differ by security policy. Choose the method that matches your policy:
Mutual trust is the default security policy. Every webhooks integration uses it, and no additional credentials are required.
Example
{ "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "product1.name", "eventTypes": [ "product.name.event.type", "product.name.event.type", "product.name.event.type" ] }, { "productId": "product2.name", "eventTypes": [ "product.name.event.type", "product.name.event.type", "product.name.event.type", "product.name.event.type", "product.name.event.type", "product.name.event.type" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" }}{ "organizationId": "organizationId", "productId": "terminalManagement", "eventTypes": [ "terminalManagement.assignment.update" ], "webhookId": "ddb9bced-c3e3-1b1d-e053-9c588e0a3c42", "name": "My Custom Webhook", "webhookUrl": "https://MyWebhookServer.com:443/simulateClient", "healthCheckUrl": "https://MyWebhookServer.com:443/simulateClientHealthCheck", "createdOn": "2022-04-28T15:39:56.928Z", "status": "ACTIVE", "description": "Sample Webhook from Developer Center", "retryPolicy": { "algorithm": "ARITHMETIC", "firstRetry": "1", "interval": "1", "numberOfRetries": "3", "deactivateFlag": "false", "repeatSequenceCount": "0", "repeatSequenceWaitTime": "0" }, "securityPolicy": { "securityType": "KEY", "digitalSignatureEnabled": "yes" }, "version": "3", "notificationScope": "SELF"}Required Fields
| Field | Description |
|---|---|
description | Description of the webhook subscription. |
name | Name of the webhook subscription. |
organizationId | Set to your organization ID or merchant ID. |
products. | For a list of event types, see Supported Products and Events. |
products. | For a list of product IDs, see Supported Products and Events. |
securityPolicy. | Set to KEY. |
webhookUrl | The URL in your system to which webhook notifications are sent. |
The OAuth security policy with client credentials is an authentication method that is designed for applications to communicate with each other. Basic authentication is the most common mechanism for authenticating a client with the client credentials. This authentication method enables services to obtain only the relevant user data without exposing the user's credentials.
Example
{ "name": "My Custom Webhook", "description": "", "organizationId": "<INSERT ORGANIZATION ID HERE>", "products": [ { "productId": "product.name", "eventTypes": [ "product.name.event.type" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "oAuth", "config": { "oAuthTokenExpiry": 365, "oAuthURL": "https://MyWebhookServer.com:8443/oAuthToken", "oAuthTokenType": "Bearer" } }}{ "organizationId" : "org1", "productId" : "terminalManagement", "eventTypes" : [ "terminalManagement.assignment.update"], "webhookId" : "d7399cb6-ff9f-72d9-e053-3cb8d30a62ee", "webhookUrl" : "https://mywebhookserver.com/simulateclient", "healthCheckUrl" : "https://mywebhookserver.com/simulateclient/healthcheck", "createdOn" : "2022-02-04T22:17:43.045Z", "status" : "INACTIVE", "retryPolicy" : { "algorithm" : "ARITHMETIC", "firstRetry" : "1", "interval" : "1", "numberOfRetries" : "3", "deactivateFlag" : "false", "repeatSequenceCount" : "0", "repeatSequenceWaitTime" : "0" }, "securityPolicy" : { "securityType" : "oAuth", "proxyType" : "internal", "digitalSignatureEnabled" : "yes", "config" : { "oAuthTokenExpiry" : "300", "oAuthURL" : "https://myoauthserver.com/simulator/v1/token", "oAuthTokenType" : "Bearer" } }, "version" : "3", "notificationScope" : "SELF"}Required Fields
| Field | Description |
|---|---|
description | Description of the webhook subscription. |
name | Name of the webhook subscription. |
organizationId | Set to your organization ID or merchant ID. |
products. | For a list of event types, see Supported Products and Events. |
products. | For a list of product IDs, see Supported Products and Events. |
securityPolicy. | |
securityPolicy. | Set to Bearer. |
securityPolicy. | This is the URL of your OAuth server. |
securityPolicy. | Set to oAuth. |
webhookUrl | The URL in your system to which webhook notifications are sent. |
The OAuth with JWT security policy is an authentication method in which your system sends a JSON Web Token. This method bypasses domain headers and minimizes the need for server-side authentication checks.
Example
{ "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<INSERT ORGANIZATION ID HERE>", "products": [ { "productId": "product.id", "eventTypes": [ "product.id.event.type" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "oAuth_JWT", "config": { "oAuthTokenExpiry": "365", "oAuthURL": "https://MyWebhookServer.com:443/oAuthToken", "oAuthTokenType": "Bearer", "additionalConfig": { "aud": "idp.api.myServer.com", "client_id": "650538A1-0000-0000-0000-932ABC57AD70", "keyId": "y-00000000000000-eAZ34pR9Ts", "scope": "merchantacq:rte:write" } } }}{ "organizationId": "organizationId", "productId": "product.id", "eventTypes": [ "product.id.event.type" ], "webhookId": "fe46bf08-3918-21ba-e053-a1588d0aeefa", "name": "My Custom Webhook", "webhookUrl": "https://MyWebhookServer.com:443/simulateClient", "healthCheckUrl": "https://MyWebhookServer.com:443/simulateClientHealthCheck", "createdOn": "2023-06-16T21:19:54.667Z", "status": "INACTIVE", "description": "Sample Webhook from Developer Center", "retryPolicy": { "algorithm": "ARITHMETIC", "firstRetry": 1, "interval": 1, "numberOfRetries": 3, "deactivateFlag": false, "repeatSequenceCount": 0, "repeatSequenceWaitTime": 0 }, "securityPolicy": { "securityType": "oAuth_JWT", "proxyType": "external", "digitalSignatureEnabled": "yes", "config": { "oAuthTokenExpiry": 365, "oAuthURL": "https://MyWebhookServer.com:443/oAuthToken", "oAuthTokenType": "Bearer", "additionalConfig": { "aud": "idp.api.myServer.com", "client_id": "650538A1-0000-0000-0000-932ABC57AD70", "keyId": "y-00000000000000-eAZ34pR9Ts", "scope": "merchantacq:rte:write" } } }, "version": "3", "deliveryType": "nrtdCentral", "notificationScope": "SELF"}Required Fields
| Field | Description |
|---|---|
description | Description of the webhook subscription. |
name | Name of the webhook subscription. |
organizationId | Set to your organization ID or merchant ID. |
products. | For a list of event types, see Supported Products and Events. |
products. | For a list of product IDs, see Supported Products and Events. |
securityPolicy. | |
securityPolicy. | |
securityPolicy. | |
securityPolicy. | |
securityPolicy. | Set to 365. |
securityPolicy. | Set to Bearer. |
securityPolicy. | This is the URL of your OAuth server. |
securityPolicy. | Set to oAuth_JWT. |
webhookUrl | The URL in your system to which webhook notifications are sent. |
Optional Fields
| Field | Description |
|---|---|
deactivateflag | Required if the healthCheckUrl field is present. Set to true to automatically activate the subscription. |
healthCheckUrl | Set to the health check URL. Required to auto-activate the subscription. If you do not include this field, the created subscription is inactive. An inactive subscription does not send notifications. |
notificationScope. | Set to the organization IDs that you want to receive notifications for when subscribed events occur in those organizations. Concatenate each organization ID with the comma character (,). |
retryPolicy. | Set to true to withhold notifications while your webhook URL or health check URL are unresponsive. The default value is false. |
retryPolicy. | The number of minutes before the notification is resent. The default value is 1. |
retryPolicy. | The number of minutes between each retry attempt. The default value is 1. |
retryPolicy. | The number of retry attempts. The default value is 3. |
retryPolicy. | The number of times to repeat the retry sequence. The default value is 0. |
retryPolicy. | The number of minutes between each repeat sequence. The default value is 0. |
Subscription ID
After sending this request, you receive a response with a subscription ID in the webhookId field. Save this ID in your system to send follow-on requests that enable you to update and manage the subscription.
Notification Scope Response Indicators
The notificationScope response field indicates which organizations receive the webhook notification. By default, notifications use the DESCENDANTS setting. To modify this setting, include the notificationScope.scopeData field in your request.
These are all possible field values:
| Value | Description |
|---|---|
SELF | Only the organization creating the webhook subscription receives notifications when a subscribed event occurs. |
DESCENDANTS (default) | The organization creating the webhook subscription receives notifications when a subscribed event occurs in their organization and in any of their children/descendant accounts in their portfolio hierarchy. This is the default notification setting. |
CUSTOM | The organization creating the webhook subscription receives notifications when a subscribed event occurs in their organization and in any organization listed in the notificationScope. request field. |
Subscription Statuses
When you create a subscription, its status is indicated in the status response field. If you did not include a health check URL in your request, the subscription is set to INACTIVE. If you included a health check URL and receives a response from the health check URL, the subscription status is set to ACTIVE.
These are the three possible statuses a subscription can be set to:
| Status | Description |
|---|---|
ACTIVE | The subscription is ready to send notifications or is actively sending notifications. |
INACTIVE | The subscription has not been activated. Add a health check URL to activate it. |
SUSPENDED | The subscription was active, but the webhook URL or the health check URL became unreachable. When the URL becomes reachable, the status changes to ACTIVE and notifications resume. |
Health Check URL
recommends that you include a health check URL in the subscription request. A health check URL ensures that you do not miss any notifications.
Including a health check URL enables to monitor your server's status for reliability. When detects that your health check URL is unresponsive, notification deliveries are withheld until your health check URL becomes responsive again.
To add a health check URL to your create a subscription request, include these fields:
healthCheckurl: set to your health check URL.deactivateflag: set totrueto enable to withhold notifications for periods when your server becomes unresponsive.
Automatic activation
After you successfully create or update a subscription, pings your health check URL within five to ten minutes:
- If receives a response, the subscription status automatically becomes
ACTIVEand notifications are delivered. - If does not receive a response, your subscription status remains
SUSPENDEDuntil receives a response.
If you did not include a health check URL when you created the subscription, pings your webhook URL for automatic activation instead. You can also activate a subscription that is not automatically activated by sending a PUT request.
Automatic revalidation
After the subscription's initial activation, continues to monitor your server status:
- If detects that your server is unavailable, your subscription status automatically updates to
SUSPENDED, and notifications are withheld. - If detects that your server is available again, your subscription status automatically updates to
ACTIVE, and all withheld notifications are delivered.
URL Validation
When a webhook subscription is created or updated, the URLs associated with that subscription are evaluated through a validation and approval process.
URL validation is designed to:
- Reduce security risk by preventing outbound calls to unapproved endpoints.
- Improve compliance through stronger review and approval controls.
- Increase transparency with clearer client-visible statuses.
- Support scale through a standardized and repeatable validation process.
URL validation applies to:
- Webhook URL (required)
- OAuth URL (if applicable)
- Health Check URL (if applicable)
Validation process:
- A webhook subscription is created or updated.
- Submitted URLs are checked against existing approval records.
- New or unknown URLs are evaluated through automated validation.
- If additional review is required, the subscription status changes to PENDING_REVIEW.
- If any URL is rejected or blocked, the subscription status changes to BLOCKED.
- If all required URLs are approved, the subscription status changes to INACTIVE.
Validation statuses: These are the statuses a subscription can be set to during URL validation:
| Status | Description |
|---|---|
| PENDING_REVIEW | One or more submitted URLs are being validated or awaiting required security approval. |
| BLOCKED | One or more URLs were rejected or identified as unsafe or non-compliant. The subscription cannot proceed until the URL(s) are updated. |
| INACTIVE | All required approvals are complete, and the subscription is ready under the existing activation flow. |
If your subscription is marked BLOCKED, one or more URLs associated with the subscription cannot be used in their current form. To continue, update the affected URLs and resubmit.
Retry Policy
If your webhook URL or health check URL are unresponsive when sent a notification, resends the notification according to the subscription's retry policy. By default, sends you 3 notification attempts, beginning 1 minute after the initial failed attempt. Retry attempts occur in 1 minute intervals if your URL remains unresponsive.
All subscriptions have a default retry policy. You can change the retry policy when you create a subscription or when you update the webhook subscription.
To configure a subscription's retry policy, include these required fields in the create a subscription request or an update a subscription request:
| Field | Description |
|---|---|
retryPolicy. | Set to one of these values: false — Notifications are not withheld when your webhook URL or health check URL are unresponsive. This value is the default. true — Notifications are withheld when your webhook URL or health check URL are unresponsive, and the subscription status updates to SUSPENDED. When the URLs become responsive again, the withheld notifications are sent and the subscription status updates to ACTIVE. |
retryPolicy. | The number of minutes before the notification is resent. The default value is 1. |
retryPolicy. | The number of minutes between each retry attempt. The default value is 1. |
retryPolicy. | The number of retry attempts. The default value is 3. |
retryPolicy. | The number of times to repeat the retry sequence. The default value is 0. |
retryPolicy. | The number of minutes between each repeat sequence. The default value is 0. |
Example: This example shows how to format a retry policy in a request.
"retryPolicy": { "firstRetry": "1", "interval": "1", "numberOfRetries": "3", "deactivateFlag": "false", "repeatSequenceCount": "0", "repeatSequenceWaitTime": "0" }Thanks for your feedback!
Last published: October 28, 2026