Create a Webhook Subscription Using OAuth with JWT {#wh-fg-subscription-oauth-jwt-api-intro} ============================================================================================ This section describes how to create a webhook subscription using OAuth with a JSON Web Token (JWT), in addition to mutual trust. 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 with JWT* security policy is an authentication method in which your system sends a JSON Web Token. This method bypasses domain headers and minimizes the need for server-side authentication checks. Health Check URL ---------------- `Cybersource` 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](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-subscription-health-check-url.md ""). Retry Policy ------------ If your webhook URL or health check URL are unresponsive when sent a notification, `Cybersource` resends the notification according to the subscription's *retry policy* . By default, `Cybersource` sends you 3 notification attempts, beginning 1 minute after the initial failed attempt. Retry attempts occur 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](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-retry.md ""). 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](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscription-manage-intro.md ""). Endpoints --------- Send a POST request to one of these endpoints: * **Test:** `POST ``https://apitest.cybersource.com``/notification-subscriptions/v2/webhooks` * **Production:** `POST ``https://api.cybersource.com``/notification-subscriptions/v2/webhooks` * **India Production:** `POST https://api.in.cybersource.com/notification-subscriptions/v2/webhooks` Required Fields for Subscribing to Webhooks Using OAuth with JWT {#wh-fg-subscription-oauth-jwt-req-fields} =========================================================================================================== 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](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro/wh-fg-product-event-types.md ""). products.productId : For a list of product IDs, see [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro/wh-fg-product-event-types.md ""). securityPolicy.config.additionalConfig.aud : securityPolicy.config.additionalConfig.client_id : securityPolicy.config.additionalConfig.keyId : securityPolicy.config.additionalConfig.scope : securityPolicy.config.oAuthTokenExpiry : Set to `365`. securityPolicy.config.oAuthTokenType : Set to `Bearer`. securityPolicy.config.oAuthUrl : This is the URL of your OAuth server. securityPolicy.securityType : Set to `oAuth_JWT`. webhookUrl : Optional Fields for Subscribing to Webhooks Using OAuth with JWT {#wh-fg-subscription-oauth-jwt-opt-fields} =========================================================================================================== deactivateflag : Required if the 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](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-subscription-health-check-url.md ""). 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](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-retry.md ""). retryPolicy.firstRetry : For more information, see [Configure the Retry Policy](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-retry.md ""). retryPolicy.interval : For more information, see [Configure the Retry Policy](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-retry.md ""). retryPolicy.numberOfRetries : For more information, see [Configure the Retry Policy](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-retry.md ""). retryPolicy.repeatSequenceCount : For more information, see [Configure the Retry Policy](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-retry.md ""). retryPolicy.repeatSequenceWaitTime : For more information, see [Configure the Retry Policy](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-retry.md ""). Example: Creating a Webhook Subscription Using OAuth with JWT {#wh-fg-subscription-oauth-jwt-ex} ================================================================================================ ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<INSERT ORGANIZATION ID HERE>", "products": [ { "productId": "product.id", "eventTypes": [ "product.id.event.type" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "oAuth_JWT", "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": "product.id", "eventTypes": [ "product.id.event.type" ], "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" } ``` **Response Codes** {#wh-fg-subscription-oauth-jwt-reply-status} =============================================================== 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](https://developer.cybersource.com/api/reference/response-codes.md ""). **Notification Scope Response Indicators** {#wh-fg-subscription-notification-scope-oauth-jwt} ============================================================================================= 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** {#wh-fg-status-oauth-jwt} =================================================== 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 `Cybersource` 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](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-subscription-health-check-url.md ""). `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. **REST Interactive Example: Create a Webhook Subscription Using OAuth with JWT** {#wh-fg-subscription-oauth-jwt-dev-ex} ======================================================================================================================= Click this image to access the interactive code example for creating a webhook subscription using OAuth with JWT. #### Figure: Create a Webhook Subscription Using OAuth with JWT [![Image and link to the interactive code example for creating a webhook subscription using OAuth with JWT.](/content/dam/documentation/cybs/en-us/topics/payments-processing/payment-services/webhooks/images/create-webhook-dev.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_create-new-webhooks_create-a-new-webhook-subscription_samplerequests-dropdown_create-webhook-using-oauth-with-jwt_liveconsole-tab-request-body "")