On This Page

Subscribe to Webhooks Using OAuth with JWT

This section describes the tasks that must be accomplished in order to subscribe to a webhook using OAuth with a JSON Web Token (JWT). You can only subscribe to one webhook per API request.

To request the service, use the endpoint specified below. After you send the request, check the response message to verify that the request was successful. A 200-level response code indicates success.

For information about response codes, see

Transaction Response Codes

Endpoint

Test:

POST apitest.visaacceptance.com/notification-subscriptions/v1/webhooks

Production:

POST api.visaacceptance.com/notification-subscriptions/v1/webhooks

Required Fields for Subscribing to Webhooks Using OAuth with JWT

eventTypes
healthCheckUrl: Required in order to auto-activate the subscription. If you do not send this field, the subscription will be created but not activated. To activate it later, you must send a PATCH request that includes a health check URL. An inactive subscription will not send notifications. For more information, see Webhook Health Check and Automatic Revalidation.
organizationId
productId: For a list of product and event types, see Product and Event Types.
securityPolicy.securityType: Set the value to
oAuth_JWT
.
securityPolicy.config.oAuthTokenExpiry: Set the value to
365
.
securityPolicy.config.oAuthUrl
securityPolicy.config.oAuthTokenType: Set the value to
Bearer
.
securityPolicy.config.additionalConfig.aud
securityPolicy.config.additionalConfig.client_id
securityPolicy.config.additionalConfig.keyId
securityPolicy.config.additionalConfig.scope
webhookUrl

Optional Fields for Subscribing to Webhooks Using OAuth with JWT

description
healthCheckUrl: This field is not required in order to create a subscription, but it is required in order to activate it. If you do not send this field during subscription, the subscription is created but not activated. To activate it later, you must send a PATCH request that includes a health check URL. An inactive subscription does not send notifications. For more information, see Webhook Health Check and Automatic Revalidation.
name
notificationScope.scopeData: Required if you submit the
notificationScope.scope
field. All organizations subscribing to the webhook must be listed in the value, separated by commas.
notificationScope.scope: For more information, see Notification Scope.
retryPolicy.deactivateFlag: See Retry Policy.
retryPolicy.firstRetry: See Retry Policy.
retryPolicy.interval: See Retry Policy.
retryPolicy.numberOfRetries: See Retry Policy.
retryPolicy.repeatSequenceCount: See Retry Policy.
retryPolicy.repeatSequenceWaitTime: See Retry Policy.

Example: Creating a Webhook Subscription Using OAuth with JWT

{
  "name": "My Custom Webhook",
  "description": "Sample Webhook from Developer Center",
  "organizationId": "organizationId",
  "productId": "terminalManagement",
  "eventTypes": [
    "terminalManagement.assignment.update"
  ],
  "webhookUrl": "https://MyWebhookServer.com:443/simulateClient",
  "healthCheckUrl": "https://MyWebhookServer.com:443/simulateClientHealthCheck",
  "notificationScope": "SELF",
  "securityPolicy": {
    "securityType": "oAuth_JWT",
    "proxyType": "external",
    "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": "terminalManagement",
  "eventTypes": [
    "terminalManagement.assignment.update"
  ],
  "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"
}

Notification Scope

The value of the

notificationScope.scope

field determines which organizations receive the notification. This field can take any of these values:

SELF: Subscribes to event notifications for only the organization requesting the webhook subscription.
DESCENDENTS: Subscribes to event notifications for all child organizations of the requesting organization.
CUSTOM: Subscribes to event notifications for organizations listed in the
notificationScope.scopeData
array. Organizations must be separated by commas.

Webhook Health Check and Automatic Revalidation

When you subscribe to a webhook event, Visa Acceptance Solutions recommends that you include a health check URL in the subscription request. Including a health check URL enables Visa Acceptance Solutions to monitor your server status for reliability. If Visa Acceptance Solutions detects that your health check URL is unresponsive, notification deliveries are withheld until your health check URL becomes responsive again. This ensures that you do not miss any notifications.

To add a health check URL to your subscription request, include the

healthCheckurl

field and set it to your health check URL. You must also include the

deactivateflag

field and set it to

true

in order for Visa Acceptance Solutions to withhold notifications for periods when your server becomes unresponsive.

Automatic Activation

After successfully creating a subscription, Visa Acceptance Solutions immediately pings your health check URL. If Visa Acceptance Solutions receives a response, the subscription status automatically becomes

ACTIVE

and notifications are delivered. When Visa Acceptance Solutions does not receive a response, your subscription status remains

SUSPENDED

until Visa Acceptance Solutions receives a response. If you did not include a health check URL when you created the subscription, Visa Acceptance Solutions pings your webhook URL for automatic activation instead. You can also activate a subscription that is not automatically activated by sending a PUT request. For more information, see Activating a Webhook Subscription.

Automatic Revalidation

After the subscription's initial activation, Visa Acceptance Solutions continues to monitor your server status. If Visa Acceptance Solutions detects that your server is unavailable, your subscription status automatically updates to

SUSPENDED

and notifications are withheld. When Visa Acceptance Solutions detects that your server is available again, your subscription status automatically updates to

ACTIVE

and all withheld notifications are delivered.

Subscription Status

A subscription can have one of three statuses:

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. See Webhook Health Check 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.

Product and Event Types

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 include only one product per API request, so you must send separate requests for each product and its associated events. Each time one of the listed events occurs, you receive a notification. If a product is not yet available, you receive the notifications when it becomes available. To obtain a list of products to which you can subscribe, see Requesting a List of Products and Events.

To create a webhooks subscription, set the

productId

field to a value listed in the product ID column, and set the

eventTypes

field array to a value or values listed in the event types column. These are the supported products and events and their respective

productId

and

eventTypes

field values:

Alternative Payments
Product ID	Event Types	Description
alternativePaymentMethods	payments.payments.updated	Notifies you that an alternative payment transaction's status has been updated.

`Fraud Management Essentials`
Product ID	Event Types	Description
fraudManagementEssentials	risk.casemanagement.decision.accept	Notifies you that a `Fraud Management Essentials` case has been accepted.
	risk.casemanagement.addnote	Notifies you that a note has been added to a `Fraud Management Essentials` case.
	risk.profile.decision.reject	Notifies you that a transaction was rejected.
	risk.casemanagement.decision.reject	Notifies you that a `Fraud Management Essentials` case has been rejected.
	risk.profile.decision.monitor	Notifies you of a profile decision to monitor a transaction.
	risk.profile.decision.review	Notifies you of a profile decision to review a transaction.

Invoicing
Product ID	Event Types	Description
customerInvoicing	invoicing.customer.invoice.send	Notifies you that an invoice has been sent.
	invoicing.customer.invoice.cancel	Notifies you that an invoice has been cancelled.
	invoicing.customer.invoice.paid	Notifies you that an invoice has been paid.
	invoicing.customer.invoice.partial-payment	Notifies you that an invoice has been partially paid.
	invoicing.customer.invoice.reminder	Notifies you 5 days before the invoice payment is due. This event is triggered if you have invoice reminders enabled in your invoice settings.
	invoicing.customer.invoice.overdue-reminder	Notifies you 1 day after the invoice payment is due. This event is triggered if you have invoice reminders enabled in your invoice settings.

Recurring Billing
Product ID	Event Types	Description
recurringBilling	rbs.subscriptions.charge.failed	Notifies you of a recurring payment failure.
	rbs.subscriptions.charge.pre-notified	Notifies you of an upcoming recurring payment.
	rbs.subscriptions.charge.created	Notifies you of successful recurring payment.

`Token Management Service`
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.

Example: Product and Events in a Webhook Subscription

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

Related Information

Set Up Webhooks