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.cybersource.com/notification-subscriptions/v1/webhooks

Production:

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

Production in India:

POST api.in.cybersource.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. The URL must use port number 8443 or 443. 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 Health Check URL.
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: The URL must use port number 8443 or 443.

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 Health Check URL.
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,
      "oAuthURLjava.io.PrintWriter@5444bba6
": "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 notificatjava.io.PrintWriter@46eead19 ions for organizations listed in the
notificationScope.scopeData
array. Organizations must be separated by commas.

Health Check URL

When you subscribe to a webhook, it is recommended that you include a health check URL. While it is not required to create a subscription, the subscription is not activated until a health check URL is added to the subscription.

deactivateflag=true

was set in the subscription request and your webhook URL or health check URL become unresponsive, any new notifications will be held and their respective subscriptions will have a status of

SUSPENDED

. When the URLs becomes responsive, your subscriptions will return to a status of

ACTIVE

and notifications will resume.

Providing a health check URL for each webhook implements two features: suspend and resume and automatic activation.

java.io.PrintWriter@20db5ba5

Suspend and Resume

The webhook delivery framework can detect when a webhook URL is unavailable and suspend the delivery of notifications. When your webhook URL is available, the webhook framework resumes delivery of webhook notifications, ensuring that there are no missed notifications. To implement this feature, you must include the

healthCheckurl

field when you send the API request that creates the webhook subscription. For more information, see Set Up Webhooks.

Automatic Activation

When you include the

healthCheckUrl

field in the API request that creates a webhook subscription, the webhook is automatically activated. If you do not add a health check URL when you create the subscription, the subscription is not activated. To activate it later, send a PATCH request that includes a health check URL. An inactive subscription does not send notifications.

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 Health Check URL.

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 the Requesting a List of Products and Events topic for the applicable Webhooks subscription workflow.

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.

`Decision Manager`
Product ID	Event Types	Description
decisionManager	risk.casemanagement.decision.accept	Notifies you that a `Decision Manager` case has been accepted.
	risk.casemanagement.decision.reject	Notifies you that a `Decision Manager` case has been rejected.
	risk.profile.decision.reject	Notifies you of a profile decision to reject a transaction.
	risk.casemanagement.addnote	Notifies you that a note has been added to a `Decision Manager` case.

`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.

Outage Alerts
Product ID	Event Types	Description
cns	cns.report.keyExpiration.detail	Notifies you that a key is expiring.

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",
    "tms.token.pan_updated",
    "tms.token.created",
    "tms.token.updated"
  ]

Related Information

Set Up Webhooks