On This Page

Create a Webhook Subscription Using Mutual Trust

This section describes how to create webhook subscription using mutual trust. You can subscribe to multiple webhook products and event types in the same request.
Mutual trust
 is the default security policy for webhooks. It is a simple authentication scheme that is included in the HTTP protocol. Mutual trust is often used in conjunction with HTTPS to provide confidentiality through encryption. You should use this key type if your integration uses the HTTP signature method for securing API requests and you require robust security measures to protect the data that is transmitted over HTTP.

Health Check URL

Visa Acceptance Solutions
 recommends that you include a health check URL in the subscription request. A health check URL ensures that you do not miss any notifications. For more information, see Webhook Health Check URL and Automatic Revalidation.

Retry Policy

If your webhook URL or health check URL are unresponsive when sent a notification,
Visa Acceptance Solutions
 resends the notification according to the subscription's
retry policy
. By default,
Visa Acceptance Solutions
 sends you 3 notification attempts, beginning 1 minute after the initial failed attempt. Each retry attempt occurs in 1 minute intervals if your URL remains unresponsive. You can configure the default retry policy when you create or update a subscription. For more information about how to configure the retry policy, see Configure the Retry Policy.

Subscription ID

IMPORTANT
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. For more information about the follow-on requests, see Manage Webhook Subscriptions Requests.

Endpoints

Send a POST request to one of these endpoints:
  • Test:
    POST
    https://apitest.visaacceptance.com
    /notification-subscriptions/v2/webhooks
  • Production:
    POST
    https://api.visaacceptance.com
    /notification-subscriptions/v2/webhooks

Required Fields for Subscribing to Webhooks Using Mutual Trust

description
name
organizationId
Set to your organization ID or merchant ID.
products.eventTypes
For a list of event types, see Supported Products and Event Types.
products.productId
For a list of product IDs, see Supported Products and Event Types.
securityPolicy.securityType
Set to
KEY
.
webhookUrl

Optional Fields for Subscribing to Webhooks Using Mutual Trust

deactivateflag
Required if
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. For more information, see Webhook Health Check URL and Automatic Revalidation.
notificationScope.scopeData
Set to the organization IDs that you want to receive notifications for when events occur in those organizations. Concatenate each organization ID with the comma character (
,
).
retryPolicy.deactivateFlag
For more information, see Configure the Retry Policy.
retryPolicy.firstRetry
For more information, see Configure the Retry Policy.
retryPolicy.interval
For more information, see Configure the Retry Policy.
retryPolicy.numberOfRetries
For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceCount
For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceWaitTime
For more information, see Configure the Retry Policy.

Example: Creating a Webhook Subscription Using Mutual Trust

{
  "name": "My Custom Webhook",
  "description": "Sample Webhook from Developer Center",
  "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>",
  "products": [
    {
      "productId": "product.name",
      "eventTypes": [
        "product.name.event.type"
      ]
    }
  ],
  "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient",
  "securityPolicy": {
    "securityType": "KEY"
  }
}
Response to a Successful Request
{
  "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"
}

Response Codes

A successful request is indicated by the 200-level response code.
For more information about all of the possible response codes you can receive, see
Transaction Response Codes
.

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:
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.scopeData
 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
Visa Acceptance Solutions
 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:
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. For more information, see Webhook Health Check URL and Automatic Revalidation.
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.