Webhooks

This section contains information on creating, retrieving, and updating webhook subscriptions. You can create, retrieve, update, or delete notification subscriptions for various events by submitting an HTTP POST, GET, PATCH, or DELETE request to the notification-subscriptions/v2/webhooks endpoint. Use the webhooks REST API to:

Create a digital signature key
Create a webhook subscription
Retrieve webhook subscription details
Update a webhook subscription
Delete a webhook subscription

When you send an API request to create a webhooks subscription, you must include the product and its associated events to which you are subscribing.

You can create webhooks subscriptions for these Token Management Service network token events:

Product ID	Event Types	Description
`tokenManagement`	`tms.networktoken.updated`	Notifies you of a network token's change in expiration date or status (suspend, resume, or deactivate).
`tokenManagement`	`tms.networktoken.provisioned`	Notifies you when a network token provision for an instrument identifier token has been successful.
`tokenManagement`	`tms.networktoken.binding`	Notifies you of the binding status of the network token with the device.

Example: Product and Network Token Events in a Webhook Subscription

{  "productId": "tokenManagement",  "eventTypes": [    "tms.networktoken.provisioned",    "tms.networktoken.updated",    "tms.networktoken.binding"  ]}

For more information, see Webhooks.

Create a Digital Signature Key

Use the information in this section to create a digital signature key. The Digital Signature Key request uses Visa's key management service to store your credentials. The Webhooks platform retrieves your credentials from key management to digitally authenticate your notifications.

You must create a digital signature key to enable to send notifications to your servers. Replace the digital signature key every year. When you generate a new digital signature key, it overrides the old key and new transactions must use the new key.

Notifications that use message-level encryption must also use the digital signature key.

Endpoint

POST /kms/egress/v2/keys-sym

Optional Notification Validation

After you set up a webhook subscription, you can validate each notification you receive using your digital signature key.

For more information, see Webhooks.

Example

{  "clientRequestAction": "CREATE",  "keyInformation": {    "provider": "nrtd",    "tenant": "merchantName",    "keyType": "sharedSecret",    "organizationId": "merchantName"  }}

{  "submitTimeUtc": "2021-03-17T06:53:06+0000",  "status": "SUCCESS",  "keyInformation": {    "provider": "NRTD",    "tenant": "merchantName",    "organizationId": "merchantName",    "keyId": "bdc0fe52-091e-b0d6-e053-34b8d30a0504",    "key": "u3qgvoaJ73rLJdPLTU3moxrXyNZA4eo5dklKtIXhsAE=",    "keyType": "sharedSecret",    "status": "Active",    "expirationDate": "2022-03-17T06:53:06+0000"  }}

Required Fields for Create a Digital Signature Key

clientRequestAction string

Set the value to CREATE.

keyInformation.expiryDuration string

Set to a number of days. We recommend 365.

keyInformation.keyType string

Set the value to sharedSecret.

keyInformation.organizationId string

Set the value to the organization ID of the organization requesting the key.

keyInformation.provider string

Set the value to nrtd.

keyInformation.tenant string

Set the value to the organization ID of the organization requesting the key.

Create Webhook Subscription

This section describes how to create a webhook subscription.

Endpoint

POST /notification-subscriptions/v2/webhooks

Example

{  "name": "My Custom Webhook",  "description": "Sample Webhook from Developer Center",  "organizationId": "merchantOrgId",  "products": [    {      "productId": "tokenManagement",      "eventTypes": [        "tms.networktoken.provisioned",        "tms.networktoken.updated",        "tms.networktoken.binding"      ]    }  ],  "webhookUrl": "https://www.yoursite.com/webhooks/tms/notifications",  "healthCheckUrl": "https://www.yoursite.com/webhooks/tms/healthcheck",  "retryPolicy": {    "algorithm": "ARITHMETIC",    "firstRetry": 1,    "interval": 1,    "numberOfRetries": 3,    "deactivateFlag": false,    "repeatSequenceCount": 0,    "repeatSequenceWaitTime": 0  },  "securityPolicy": {    "securityType": "KEY"  }}

{  "organizationId": "merchantOrgId",  "productId": "tokenManagement",  "eventTypes": [    "tms.networktoken.provisioned",    "tms.networktoken.updated",    "tms.networktoken.binding"  ],  "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "webhookUrl": "https://www.yoursite.com/webhooks/tms/notifications",  "healthCheckUrl": "https://www.yoursite.com/webhooks/tms/healthcheck",  "createdOn": "2026-07-07T17:24:05.116Z",  "status": "ACTIVE",  "retryPolicy": {    "algorithm": "ARITHMETIC",    "firstRetry": 1,    "interval": 1,    "numberOfRetries": 3,    "deactivateFlag": false,    "repeatSequenceCount": 0,    "repeatSequenceWaitTime": 0  },  "securityPolicy": {    "securityType": "KEY",    "proxyType": "external",    "digitalSignatureEnabled": "yes"  },  "version": "3",  "deliveryType": "nrtdCentral",  "notificationScope": "DESCENDANTS"}

Required Fields for Create Webhook Subscription

name string

Name of the webhook subscription.

description string

Description of the webhook subscription.

organizationId string

Set to the organization ID. See the preceding callout for which organization ID to use.

products.productId string

Set to tokenManagement.

products.eventTypes array

An array of event types to which you are subscribing. Valid values:

tms.networktoken.provisioned
tms.networktoken.updated
tms.networktoken.binding

webhookUrl string

Set to the URL where you want to receive webhook notifications.

securityPolicy.securityType string

Set to KEY.

Optional Fields for Create Webhook Subscription

healthCheckUrl string

Set to the health check URL. Required to auto-activate the subscription. If you do not include this field, the created subscription is INACTIVE.

retryPolicy.deactivateFlag boolean

Set to true to withhold notifications while your webhook URL or health check URL are unresponsive. The default value is false.

retryPolicy.firstRetry integer

The number of minutes before the notification is resent. The default value is 1.

retryPolicy.interval integer

The number of minutes between each retry attempt. The default value is 1.

retryPolicy.numberOfRetries integer

The number of retry attempts. The default value is 3.

retryPolicy.repeatSequenceCount integer

The number of times to repeat the retry sequence. The default value is 0.

retryPolicy.repeatSequenceWaitTime integer

The number of minutes between each repeat sequence. The default value is 0.

Subscription Statuses

Status	Description
`ACTIVE`	The subscription is ready to send notifications or is actively sending notifications.
`INACTIVE`	The subscription has not been activated. Add a `healthCheckUrl` 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.

Retrieve Webhook Subscription Details

This section describes how to retrieve webhook subscription details.

Endpoint

GET /notification-subscriptions/v2/webhooks/{webhookId}

Example

{  "organizationId": "merchantOrgId",  "productId": "tokenManagement",  "eventTypes": [    "tms.networktoken.provisioned",    "tms.networktoken.updated",    "tms.networktoken.binding"  ],  "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "webhookUrl": "https://www.yoursite.com/webhooks/tms/notifications",  "healthCheckUrl": "https://www.yoursite.com/webhooks/tms/healthcheck",  "createdOn": "2026-07-07T17:24:05.116Z",  "status": "SUSPENDED",  "retryPolicy": {    "algorithm": "ARITHMETIC",    "firstRetry": 1,    "interval": 1,    "numberOfRetries": 3,    "deactivateFlag": false,    "repeatSequenceCount": 0,    "repeatSequenceWaitTime": 0  },  "securityPolicy": {    "securityType": "KEY",    "digitalSignatureEnabled": "yes"  },  "version": "3",  "deliveryType": "nrtdCentral",  "notificationScope": "DESCENDANTS"}

Update Webhook Subscription

This section describes how to update a webhook subscription.

Endpoint

PATCH /notification-subscriptions/v2/webhooks/{webhookId}

Example

{  "webhookUrl": "https://www.yoursite.com/webhooks/tms/updated-notifications",  "products": [    {      "productId": "tokenManagement",      "eventTypes": [        "tms.networktoken.provisioned",        "tms.networktoken.updated"      ]    }  ]}

{  "organizationId": "merchantOrgId",  "productId": "tokenManagement",  "eventTypes": [    "tms.networktoken.provisioned",    "tms.networktoken.updated"  ],  "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "webhookUrl": "https://www.yoursite.com/webhooks/tms/updated-notifications",  "healthCheckUrl": "https://www.yoursite.com/webhooks/tms/healthcheck",  "createdOn": "2026-07-07T17:24:05.116Z",  "status": "ACTIVE",  "retryPolicy": {    "algorithm": "ARITHMETIC",    "firstRetry": 1,    "interval": 1,    "numberOfRetries": 3,    "deactivateFlag": false,    "repeatSequenceCount": 0,    "repeatSequenceWaitTime": 0  },  "securityPolicy": {    "securityType": "KEY",    "digitalSignatureEnabled": "yes"  },  "version": "3",  "deliveryType": "nrtdCentral",  "notificationScope": "DESCENDANTS"}

Optional Fields for Update Webhook Subscription

webhookUrl string

Update the URL where you want to receive webhook notifications.

products.eventTypes array

Update the array of event types to which you are subscribing.

healthCheckUrl string

Update the health check URL.

retryPolicy object

Update the retry policy settings.

Delete Webhook Subscription

This section describes how to delete a webhook subscription.

Endpoint

DELETE /notification-subscriptions/v2/webhooks/{webhookId}

Example

{  "status": "successfully deleted"}

Was this page helpful?

Last published: October 28, 2026

Example: Product and Network Token Events in a Webhook Subscription

Create a Digital Signature Key

Optional Notification Validation

Example

Create Webhook Subscription

Example

Subscription Statuses

Retrieve Webhook Subscription Details

Example

Update Webhook Subscription

Example

Delete Webhook Subscription

Example

Not available for your audience