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/v1/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 the Webhooks Implementation Guide.

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 the Webhooks Implementation Guide.

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

clientRequestAction string · Required

Set the value to CREATE.

keyInformation.expiryDuration string · Required

Set to a number of days. We recommend 365.

keyInformation.keyType string · Required

Set the value to sharedSecret.

keyInformation.organizationId string · Required

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

keyInformation.provider string · Required

Set the value to nrtd.

keyInformation.tenant string · Required

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/v1/webhooks

Example

{  "organizationId": "merchantOrgId",  "productId": "tokenManagement",  "url": "https://www.yoursite.com/webhooks/tms/notifications",  "eventTypes": [    "tms.networktoken.provisioned",    "tms.networktoken.updated",    "tms.networktoken.binding"  ]}

{  "submitTimeUtc": "2023-04-12T10:15:30+0000",  "status": "SUCCESS",  "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "organizationId": "merchantOrgId",  "productId": "tokenManagement",  "url": "https://www.yoursite.com/webhooks/tms/notifications",  "eventTypes": [    "tms.networktoken.provisioned",    "tms.networktoken.updated",    "tms.networktoken.binding"  ]}

Required Fields

organizationId string · Required

Set to the organization ID.

productId string · Required

Set to tokenManagement.

url string · Required

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

eventTypes array · Required

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

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

Retrieve Webhook Subscription Details

This section describes how to retrieve webhook subscription details.

Endpoint

GET /notification-subscriptions/v1/webhooks/{webhookID}

Example

{  "submitTimeUtc": "2023-04-12T10:15:30+0000",  "status": "SUCCESS",  "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "organizationId": "merchantOrgId",  "productId": "tokenManagement",  "url": "https://www.yoursite.com/webhooks/tms/notifications",  "eventTypes": [    "tms.networktoken.provisioned",    "tms.networktoken.updated",    "tms.networktoken.binding"  ]}

Update Webhook Subscription

This section describes how to update a webhook subscription.

Endpoint

PATCH /notification-subscriptions/v1/webhooks/{webhookID}

Example

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

{  "submitTimeUtc": "2023-04-12T11:20:45+0000",  "status": "SUCCESS",  "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",  "organizationId": "merchantOrgId",  "productId": "tokenManagement",  "url": "https://www.yoursite.com/webhooks/tms/updated-notifications",  "eventTypes": [    "tms.networktoken.provisioned",    "tms.networktoken.updated"  ]}

Optional Fields

url string · Optional

Update the URL where you want to receive webhook notifications.

eventTypes array · Optional

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

Delete Webhook Subscription

This section describes how to delete a webhook subscription.

Endpoint

DELETE /notification-subscriptions/v1/webhooks/{webhookID}

Example

{  "submitTimeUtc": "2023-04-12T12:30:15+0000",  "status": "SUCCESS",  "message": "Webhook subscription deleted successfully",  "webhookId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}

Was this page helpful?

Last published: September 29, 2026