On This Page {#jumplink-list} [Markdown](/docs/vas/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscribe-intro/wh-fg-subscription-oauth-api-intro.md) Filter FILTER BY TAG Create a Webhook Subscription Using OAuth {#wh-fg-subscription-oauth-api-intro} =============================================================================== 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](/docs/vas/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, `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](/docs/vas/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/vas/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.visaacceptance.com``/notification-subscriptions/v2/webhooks` * **Production:** `POST ``https://api.visaacceptance.com``/notification-subscriptions/v2/webhooks` Required Fields for Subscribing to Webhooks Using OAuth {#wh-fg-subscription-oauth-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/vas/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). products.productId : For a list of product IDs, see [Supported Products and Event Types](/docs/vas/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). 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 {#wh-fg-subscription-oauth-opt-fields} ============================================================================================== 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](/docs/vas/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 subscribed events occur in those organizations. Concatenate each organization ID with the comma character (`,`). retryPolicy.deactivateFlag : For more information, see [Configure the Retry Policy](/docs/vas/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/vas/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/vas/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/vas/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/vas/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/vas/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-retry.md ""). Example: Creating a Webhook Subscription Using OAuth {#wh-fg-subscription-oauth-ex} =================================================================================== ``` { "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** {#wh-fg-subscription-oath-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.visaacceptance.com/api/reference/response-codes.md ""). **Notification Scope Response Indicators** {#wh-fg-subscription-notification-scope-oauth} ========================================================================================= 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} =============================================== 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](/docs/vas/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. RELATED TO THIS PAGE