On This Page

Create a Webhook Subscription Using OAuth

This section describes how to create a webhook subscription using the OAuth 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.
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
Visa Acceptance Solutions
 services to obtain only the relevant user data without exposing the user's credentials.

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 OAuth

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.config.oAuthTokenExpiry
securityPolicy.config.oAuthTokenType
Set to
Bearer
securityPolicy.config.oAuthURL
securityPolicy.securityType
Set to
oAuth
.
webhookUrl

Optional Fields for Subscribing to Webhooks Using OAuth

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 subscribed 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 OAuth

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

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.