Create a Webhook Subscription {#wh-fg-subscription-mutual-api-intro} ==================================================================== This section describes how to create webhook subscription using mutual trust. Mutual trust is the default security policy. For more information, see [Set Up Your Security](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-server-security.md ""). You can subscribe to multiple webhook products and event types in the same request. Health Check URL {#wh-fg-subscription-mutual-api-intro_healthcheck-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 ""). URL Validation {#wh-fg-subscription-mutual-api-intro_url-validation} -------------------------------------------------------------------- When a webhook subscription is created or updated, the URLs associated with that subscription are evaluated through a validation and approval process that can take 1-2 business days. See [URL Review and Approval Process](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscribe-intro/wh-fg-url-validation.md "") Retry Policy {#wh-fg-subscription-mutual-api-intro_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 {#wh-fg-subscription-mutual-api-intro_subscribe} ---------------------------------------------------------------- > 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 {#wh-fg-subscription-mutual-api-intro_endpoint-create-sub} -------------------------------------------------------------------- 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 {#wh-fg-subscription-mutual-req-fields} =================================================================================== description : Description of the webhook subscription. name : Name of the webhook subscription. 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.securityType : Set to `KEY`. webhookUrl : The URL in your system to which webhooks notifications will be sent. Optional Fields for Subscribing to Webhooks {#wh-fg-subscription-mutual-opt-fields} =================================================================================== deactivateflag : Required when 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 have receive notifications 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 {#wh-fg-subscription-mutual-ex} ======================================================================== ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "product1.name", "eventTypes": [ "product.name.event.type" "product.name.event.type" "product.name.event.type" ] } { "productId": "product2.name", "eventTypes": [ "product.name.event.type" "product.name.event.type" "product.name.event.type" "product.name.event.type" "product.name.event.type" "product.name.event.type" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` Response to a Successful Request ``` { "organizationId": "organizationId", "productId": "terminalManagement", "eventTypes": [ "terminalManagement.assignment.update" ], "webhookId": "ddb9bced-c3e3-1b1d-e053-9c588e0a3c42", "name": "My Custom Webhook", "webhookUrl": "https://MyWebhookServer.com:443/simulateClient", "healthCheckUrl": "https://MyWebhookServer.com:443/simulateClientHealthCheck", "createdOn": "2022-04-28T15:39:56.928Z", "status": "ACTIVE", "description": "Sample Webhook from Developer Center", "retryPolicy": { "algorithm": "ARITHMETIC", "firstRetry": "1", "interval": "1", "numberOfRetries": "3", "deactivateFlag": "false", "repeatSequenceCount": '0", "repeatSequenceWaitTime": "0" }, "securityPolicy": { "securityType": "KEY", "digitalSignatureEnabled": "yes" }, "version": "3", "notificationScope": "SELF" } ``` **Response Codes** {#wh-fg-subscription-mutual-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-mutual} ========================================================================================== 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-mutual} ================================================ 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 five possible statuses a subscription can be set to: `PENDING_REVIEW` : One or more submitted URLs are being validated or awaiting required security approval. `BLOCKED` : One or more URLs were rejected or identified as unsafe or non-compliant. The subscription cannot proceed until the URL(s) are updated. `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** {#wh-fg-subscription-mutual-ex-dev} =============================================================================================== Click this image to access the interactive code example for creating a webhook subscription. #### Figure: Create a Webhook Subscription [![Image and link to the interactive code example for creating a webhook subscription.](/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-client-credentials_liveconsole-tab-request-body "")