On This Page {#jumplink-list} [Markdown](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks.md) Webhooks Implementation Guide {#webhooks-about-guide} ===================================================== This guide provides information about Webhook features that you can include in your system: * Multiple security options. For example, server security policy and digital signature verification. * Multiple possible workflows based on the security policy you choose. * The process for setting up and using the feature. {#webhooks-about-guide_ul_nvj_cyh_mxb} Convention : This special statement is used in this document: > IMPORTANT > An *Important* statement contains information essential to successfully completing a task or learning a concept. Related Documentation : Refer to the Technical Documentation Portal for more technical documentation: [https://developer.cybersource.com/docs.html](https://developer.cybersource.com/docs.md "") Customer Support : For support information about any service, visit the Support Center: Limited Availability Release {#wh-fg-la-release} ================================================ This document provides information about the limited availability release of the Webhooks REST API. Recent Revisions to This Document {#wh-fg-doc-revisions} ======================================================== 25.10.01 -------- This revision contains only editorial changes and no technical updates. 25.09.02 -------- Added support for the `tms.networktoken.binding` webhook event type, which notifies you of the binding status of a network token to a device. See [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). 25.09.01 -------- Added examples of creating a webhook subscription for `eCheck` events. See the `eCheck` section in [Request Examples for Creating a Subscription for all Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscribe-intro/wh-fg-product-ex-intro/wh-fg-product-payments-intro.md ""). 25.08.01 -------- This guide has been reorganized. 25.03.01 -------- Managing Subscriptions : Added additional information about why you should include a health check URL when subscribing to a webhook event. 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 ""). Product and Events : Removed support for the `cns.report.keyExpiration.detail` webhook event type, which would notify you when a key is expiring. See [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). 25.02.02 -------- Products and Events : Added support for new Invoicing product events. See [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). 25.02.01 -------- Products and Events : Added support for new Invoicing product events. See [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). Updated product event types and descriptions. See [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). VISA Platform Connect: Specifications and Conditions for Resellers/Partners {#vpc-partner-reseller-disclaimer} ============================================================================================================== The following are specifications and conditions that apply to a Reseller/Partner enabling its merchants through Cybersource for Visa Platform Connect ("VPC") processing. Failure to meet any of the specifications and conditions below is subject to the liability provisions and indemnification obligations under Reseller/Partner's contract with Visa/Cybersource. 1. Before boarding merchants for payment processing on a VPC acquirer's connection, Reseller/Partner and the VPC acquirer must have a contract or other legal agreement that permits Reseller/Partner to enable its merchants to process payments with the acquirer through the dedicated VPC connection and/or traditional connection with such VPC acquirer. 2. Reseller/Partner is responsible for boarding and enabling its merchants in accordance with the terms of the contract or other legal agreement with the relevant VPC acquirer. 3. Reseller/Partner acknowledges and agrees that all considerations and fees associated with chargebacks, interchange downgrades, settlement issues, funding delays, and other processing related activities are strictly between Reseller and the relevant VPC acquirer. 4. Reseller/Partner acknowledges and agrees that the relevant VPC acquirer is responsible for payment processing issues, including but not limited to, transaction declines by network/issuer, decline rates, and interchange qualification, as may be agreed to or outlined in the contract or other legal agreement between Reseller/Partner and such VPC acquirer. DISCLAIMER: NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR ANY ERRORS OR OMISSIONS BY THE Visa Platform Connect ACQUIRER IN PROCESSING TRANSACTIONS. NEITHER VISA NOR CYBERSOURCE WILL BE RESPONSIBLE OR LIABLE FOR RESELLER/PARTNER BOARDING MERCHANTS OR ENABLING MERCHANT PROCESSING IN VIOLATION OF THE TERMS AND CONDITIONS IMPOSED BY THE RELEVANT Visa Platform Connect ACQUIRER. Introduction to Webhooks {#wh-fg-intro} ======================================= Webhooks are automated notifications that are generated and sent to you when specific system events occur. By using the Webhooks REST API, you can subscribe to receive these notifications for events of your choice and designate a URL in your system to receive the notifications. This is helpful for events that are not a part of an API request and response, or are not available through the Reporting API. For example, you can receive webhook notifications when these events occur: * Fraud alerts * Invoice status updates * Network token is provisioned * Transaction monitoring * Recurring billing You can also configure your system to respond to the events in any way you choose. The Webhooks REST API enables you to: * Create webhook subscriptions to receive automatic system notifications * Update and delete existing webhook subscriptions * Check the status of a webhook notification * Retrieve webhook notification history and details For more information about the products and event types that you can receive notifications for, see [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). Benefits -------- The Webhooks API provides these key benefits: * Visibility into system events that are otherwise not visible. * Ability to respond to events programmatically and to automate workflows. Test Methods for Webhooks ------------------------- You can test the Webhooks REST API using the Postman application or the `Cybersource` Developer Center's live console. **Postman** : A Postman collection is available for you to test the Webhooks REST API. Contact your account manager to request the collection. **Developer Center Live Console** : The `Cybersource` Developer Center offers the live console for you to test complete examples and view the API field descriptions. See the [Webhooks](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks "") section in the REST API Reference. How to Prepare Your System to Support Webhooks {#wh-fg-intro-prepare} ===================================================================== You must complete these prerequisites before beginning to set up your webhooks subscriptions. Webhooks Server --------------- You must set up a server with a URL to receive webhook notifications. You can also set up an additional URL for the health check service. For more information about how `Cybersource` uses your health check URL, 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 ""). Security Policy Options ----------------------- Your system must support the *mutual trust* security policy to authenticate webhook notifications. Mutual trust is a simple authentication scheme that is included in the HTTP protocol. It is often used in conjunction with HTTPS to provide confidentiality through encryption. In addition to mutual trust, you can also use the *OAuth* or *OAuth JWT* security policy to authenticate your webhook notifications. `Business Center` Account and Security Keys ------------------------------------------- You must have an organization or merchant account (MID) and REST API security keys. If you do not have an account, you can sign up for *test* account on the Developer Center: [`https://developer.cybersource.com/hello-world/sandbox.html`](https://developer.cybersource.com/hello-world/sandbox.md "") During the test account signup, you receive a REST API security key to test the APIs. To create new REST API security keys, see the [*Creating and Using Security Keys User Guide*](https://developer.cybersource.com/docs/cybs/en-us/security-keys/user/all/ada/security-keys/keys-about-guide.md ""). Getting Started with the REST API --------------------------------- To begin implementing webhooks through `Cybersource`, you must set up your system to be REST compliant. `Cybersource` uses the REST architecture for developing web services. REST enables communication between a client and server using HTTP protocols. If you have not set up secure communications between your client and server using either a **JSON Web Token** or **HTTP signature**, see the [Getting Started with the REST API](https://developer.cybersource.com/docs/cybs/en-us/platform/developer/all/rest/rest-getting-started/restgs-intro.md ""). How to Set Up Webhook Subscriptions {#wh-fg-workflow-options} ============================================================= Follow these steps to set up your system to support the Webooks REST API. Some of these steps are dependent on your system's security policy. #### Figure: Set Up Webhook Subscriptions Workflow ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/webhooks-setup-workflow-600x460.svg/jcr:content/renditions/original) 1. Configure your server security to receive webhooks notifications. For more information, see [Set Up Your Server Security](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-server-security.md ""). 2. Create a REST API security key that is compliant with your security policy. Security keys are used to authenticate the requests you send to `Cybersource`. You must create separate keys for the testing and production environments. For more information, see [Create REST API Keys](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/webhooks-keys-intro.md ""). 3. Request a digital signature key from `Cybersource`. For more information, see [Create a Digital Signature Key](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-key-dig-sig-intro.md ""). 4. If your system uses the *OAuth* or *OAuth with JWT* security policy, you must provide your OAuth credentials to `Cybersource`. For more information, see [Provide Your OAuth Credentials](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-oauth-cred-intro.md ""). 5. Request a list of the products that your organization is enabled to receive webhook notifications for. For more information, see [Retrieve a List of Products and Events](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-list-intro.md ""). 6. Create your webhook subscription event notifications. For more information, see [Create a Webhook Subscription](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscribe-intro.md ""). Optional Set Up Tasks {#wh-fg-workflow-options_opt-tasks} --------------------------------------------------------- These are optional tasks you can complete after creating a webhook subscription. * Include a health check URL to enable `Cybersource` to monitor your server's status for reliability. 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 ""). * Customize the retry policy for unresponsive webhook and health check URLs. 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 ""). * Validate your digital signature. For more information, see [Validate a Webhook Notification](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-validate-intro.md ""). Supported Products and Event Types {#wh-fg-product-event-types} =============================================================== This section describes all of the products and event types that are supported by the Webhooks `REST API`. When you create a webhook subscription, you must include a `Cybersource` *product* and one of its corresponding *event types* in your request. You can include multiple products and event types in the same request. Every time one of the events that you subscribe to occurs, you receive a notification. If you subscribe to a product that is not enabled for your account, you receive a notification when it is enabled. To retrieve a list of the enabled products that your organization can subscribe to, see [Retrieve a List of Products and Events](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-list-intro.md ""). When you send a *create a webhook subscription* request, set the productId field to a value listed in the Product ID column. Set the eventTypes field array to a value listed in the Event Types column. If you are subscribing to multiple products and event types, separate each value with the comma character (`,`). For reference examples of how to properly format these fields and values in a request, see [Examples of all Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscribe-intro/wh-fg-product-ex-intro.md ""). These are all of the webhook supported products, event types, and their corresponding field values: Alternative Payment Methods {#wh-fg-product-event-types_alt-pay} ---------------------------------------------------------------- | Product ID | Event Types | Description | |-----------------------------|-----------------------------|---------------------------------------------------------------------------------| | `alternativePaymentMethods` | `payments.payments.updated` | Notifies you that an alternative payment transaction's status has been updated. | `eCheck` {#wh-fg-product-event-types_echeck} -------------------------------------------- | Product ID | Event Types | Description | |------------|------------------------------|-----------------------------------------------------------| | `eCheck` | `payments.credits.accepted` | Notifies you of a successful `eCheck` credit transaction. | | `eCheck` | `payments.credits.failed` | Notifies you of an `eCheck` credit transaction failure. | | `eCheck` | `payments.payments.accepted` | Notifies you of a successful `eCheck` debit transaction. | | `eCheck` | `payments.payments.failed` | Notifies you of an `eCheck` debit transaction failure. | | `eCheck` | `payments.voids.accepted` | Notifies you of a successful `eCheck` void transaction. | | `eCheck` | `payments.voids.failed` | Notifies you of an `eCheck` void transaction failure. | `Fraud Management Essentials` {#wh-fg-product-event-types_fme} -------------------------------------------------------------- | Product ID | Event Types | Description | |-----------------------------|---------------------------------------|----------------------------------------------------------------------------------| | `fraudManagementEssentials` | `risk.casemanagement.decision.accept` | Notifies you that a `Fraud Management Essentials` case has been accepted. | | `fraudManagementEssentials` | `risk.casemanagement.addnote` | Notifies you that a note has been added to a `Fraud Management Essentials` case. | | `fraudManagementEssentials` | `risk.profile.decision.reject` | Notifies you that a transaction was rejected. | | `fraudManagementEssentials` | `risk.casemanagement.decision.reject` | Notifies you that a `Fraud Management Essentials` case has been rejected. | | `fraudManagementEssentials` | `risk.profile.decision.monitor` | Notifies you of a profile decision to monitor a transaction. | | `fraudManagementEssentials` | `risk.profile.decision.review` | Notifies you of a profile decision to review a transaction. | Invoicing {#wh-fg-product-event-types_invoicing} ------------------------------------------------ | Product ID | Event Types | Description | |---------------------|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------| | `customerInvoicing` | `invoicing.customer.invoice.send` | Notifies you that an invoice has been sent. | | `customerInvoicing` | `invoicing.customer.invoice.cancel` | Notifies you that an invoice has been cancelled. | | `customerInvoicing` | `invoicing.customer.invoice.paid` | Notifies you that an invoice has been paid. | | `customerInvoicing` | `invoicing.customer.invoice.partial-payment` | Notifies you that an invoice has been partially paid. | | `customerInvoicing` | `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. | | `customerInvoicing` | `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. | Payments -------- | Product ID | Event Types | Description | |------------|------------------------------------|---------------------------------------------------------------------------| | `payments` | `payments.capture.status.accepted` | Notifies you that a payment capture request is accepted by `Cybersource`. | | `payments` | `payments.capture.status.updated` | Notifies you that a payment capture is updated. | `Pay by Link` ------------- | Product ID | Event Types | Description | |-------------|------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| | `payByLink` | `payByLink.merchant.payment` | Merchants can subscribe to this event type to automate how their system is informed when a customer completes a payment. | | `payByLink` | `payByLink.customer.payment` | Partner resellers can subscribe to this event type to control the distribution of the payment confirmation email sent to their merchants' customers. | Recurring Billing {#wh-fg-product-event-types_rb} ------------------------------------------------- | Product ID | Event Types | Description | |--------------------|-----------------------------------------|------------------------------------------------| | `recurringBilling` | `rbs.subscriptions.charge.failed` | Notifies you of a recurring payment failure. | | `recurringBilling` | `rbs.subscriptions.charge.pre-notified` | Notifies you of an upcoming recurring payment. | | `recurringBilling` | `rbs.subscriptions.charge.created` | Notifies you of successful recurring payment. | `Token Management Service` {#wh-fg-product-event-types_tms} ----------------------------------------------------------- | 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. | | `tokenManagement` | `tms.networktoken.binding` | Notifies you of the binding status of a network token with a device. | Set Up Your Server Security {#wh-fg-server-security} ==================================================== Complete these tasks to configure your server to receive secure webhook notifications. Allowlist --------- Add these IP addresses to your allowlist to permit `Cybersource` to deliver your webhook notifications: * 198.241.206.21 * 198.241.207.21 Trusting the Root Certificate ----------------------------- Download the *Visa Corporate Root CA G2* certificate from the Visa Public Key Infrastructure webpage, and add it to your Java keystore: [`http://enroll.visaca.com`](http://enroll.visaca.com "") Create REST API Keys {#webhooks-keys-intro} =========================================== The Webhooks REST API requires you to create a *shared secret key pair* . You may have already completed this requirement if your system is currently REST compliant. If you are using the OAuth with JWT security policy, you must also create a *P12 certificate* . The shared secret key pair and P12 certificate are also known as REST API keys. REST API keys are used to enable secure communication between you and `Cybersource` when using the REST API. * **Shared secret key pair:** A key pair used for HTTP signature authentication. It is consists of a key and a shared secret key. See [Create a Shared Secret Key Pair](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/webhooks-keys-intro/webhooks-keys-shared-secret.md ""). * **P12 certificate:** A key used for JSON Web Token authentication. It consists of *.p12* file and a password that you must set to use the file. See [Create a P12 Certificate](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/webhooks-keys-intro/webhooks-keys-p12.md ""). When using the test and production environments, you must create separate keys for each environment. Securely store your created keys in your system. You must be able to access your key credentials while implementing and managing webhook subscriptions. REST API keys expire after 3 years. Create a Shared Secret Key Pair {#webhooks-keys-shared-secret} ============================================================== The Webhook REST API requires you to create a shared secret key pair. You may have already completed this requirement if your system is currently REST compliant. Follow these steps to create a shared secret key pair. 1. Log in to the `Business Center`: * **Test:** [`https://businesscentertest.cybersource.com`](https://businesscentertest.cybersource.com/ebc2/ "") * **Production:** [`https://businesscenter.cybersource.com`](https://businesscenter.cybersource.com/ebc2/ "") {#webhooks-keys-shared-secret_step-1} {#webhooks-keys-shared-secret_step-1} 2. On the left navigation panel, choose ![](/content/dam/new-documentation/documentation/en-us/common/images/ebc/ebc-icon-pymt-config.svg/jcr:content/renditions/original) Payment Configuration \> Key Management. ![](/content/dam/new-documentation/documentation/en-us/topics/platform/rest/getting-started/images/left-navigation.png/jcr:content/renditions/original) {#webhooks-keys-shared-secret_step-2} {#webhooks-keys-shared-secret_step-2} 3. Click + Generate key. ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/sec-keys/images/generate-key.png/jcr:content/renditions/original) {#webhooks-keys-shared-secret_step-3} {#webhooks-keys-shared-secret_step-3} 4. Under REST APIs, choose **REST -- Shared Secret** and then click **Generate key**. ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/sec-keys/images/security-keys-create-key.png/jcr:content/renditions/original) ![](/content/dam/new-documentation/documentation/en-us/topics/platform/rest/getting-started/images/generate-key-bttn.png/jcr:content/renditions/original) The REST API Shared Secret Key page appears. {#webhooks-keys-shared-secret_d10e26} {#webhooks-keys-shared-secret_d10e26} 5. Click **Download key** ![](/content/dam/new-documentation/documentation/en-us/common/images/ebc/ebc-bttn-download.svg/jcr:content/renditions/original) . The .pem file is downloaded to your desktop. ![](/content/dam/new-documentation/documentation/en-us/topics/platform/rest/getting-started/images/shared-secret-key-download.png/jcr:content/renditions/original) {#webhooks-keys-shared-secret_d10e46} {#webhooks-keys-shared-secret_d10e46} You can create or upload another key by clicking **Generate another key**. To view all of your created keys, use the Key Management page. IMPORTANT Securely store the shared secret key pair in your system. You must be able to retrieve these credentials to implement the Webhooks REST API. Create a P12 Certificate {#webhooks-keys-p12} ============================================= If you are using the OAuth with JWT security policy, you must create a P12 certificate in addition to a shared secret key pair. You may have already completed this requirement if your system is currently REST compliant. Follow these steps to create a *.p12* file if you are using JSON Web Tokens to secure communication. 1. Log in to the `Business Center`: * **Test:** [`https://businesscentertest.cybersource.com`](https://businesscentertest.cybersource.com/ebc2/ "") * **Production:** [`https://businesscenter.cybersource.com`](https://businesscenter.cybersource.com/ebc2/ "") {#webhooks-keys-p12_d11e23} {#webhooks-keys-p12_d11e23} 2. On the left navigation panel, choose ![](/content/dam/new-documentation/documentation/en-us/common/images/ebc/ebc-icon-pymt-config.svg/jcr:content/renditions/original) Payment Configuration \> Key Management. ![](/content/dam/new-documentation/documentation/en-us/topics/platform/rest/getting-started/images/left-navigation.png/jcr:content/renditions/original) {#webhooks-keys-p12_d11e53} {#webhooks-keys-p12_d11e53} 3. Click + Generate key. ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/sec-keys/images/generate-key.png/jcr:content/renditions/original) {#webhooks-keys-p12_d11e67} {#webhooks-keys-p12_d11e67} 4. Under REST APIs, choose REST -- Certificate, and then click Generate key. If you are using a *portfolio* account, the Key options window appears, giving you the choice to create a meta key. For more information about how to create a meta key, see [Meta Key Creation and Management](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/keys-meta-intro.md ""). ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/sec-keys/images/p12-key-select.png/jcr:content/renditions/original) {#webhooks-keys-p12_d11e79} {#webhooks-keys-p12_d11e79} 5. Click Download key ![](/content/dam/new-documentation/documentation/en-us/common/images/ebc/ebc-bttn-download.svg/jcr:content/renditions/original) . ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/sec-keys/images/p12-key-generate.png/jcr:content/renditions/original) {#webhooks-keys-p12_d11e103} {#webhooks-keys-p12_d11e103} 6. Create a password for the certificate by entering the password into the New Password and Confirm Password fields, and then click Generate key. ![](/content/dam/new-documentation/documentation/en-us/topics/platform/rest/getting-started/images/restgs-set-pass.png/jcr:content/renditions/original) The *.p12* file downloads to your desktop. If prompted by your system, approve the location for where the key downloads. {#webhooks-keys-p12_d11e118} {#webhooks-keys-p12_d11e118} You can create or upload another key by clicking **Generate another key**. To view all of your created keys, use the Key Management page. > IMPORTANT > Securely store the *.p12* file and password in your system. Create a Digital Signature Key {#wh-fg-key-dig-sig-intro} ========================================================= This section describes how to create a *digital signature key* . You must create a digital signature key in order for `Cybersource` to send notifications to your servers. You only need to send this request once for each account. Sending this request again using the same account credentials results in the same digital signature key. > IMPORTANT Store the created digital signature key in a secure location in your system. Optional Notification Validation -------------------------------- After you set up a webhook subscription, you can validate each notification you receive using your digital signature key. When `Cybersource` sends you a notification, your digital signature key is included in the notification's header. You can configure your system to validate that each notification contains your digital signature key in its header. Validating a webhook notification verifies the notification's integrity and prevents replay attacks. For more information, see [Validate a Webhook Notification](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-optional-intro/wh-fg-optional-validate-intro.md ""). Endpoints --------- Send a POST request to one of these endpoints: * **Test:** `POST ``https://apitest.cybersource.com``/kms/egress/v2/keys-sym` * **Production:** `POST ``https://api.cybersource.com``/kms/egress/v2/keys-sym` * **India Production:** `POST https://api.in.cybersource.com/kms/egress/v2/keys-sym` Required Fields for Creating a Digital Signature Key {#wh-fg-key-dig-sig-req-fields} ==================================================================================== clientRequestAction : Set the value to `CREATE`. keyInformation.expiryDuration : keyInformation.keyType : Set the value to `sharedSecret`. keyInformation.organizationId : Set the value to the organization ID of the organization requesting the key. keyInformation.provider : Set the value to `nrtd`. keyInformation.tenant : Set the value to the organization ID of the organization requesting the key. Example: Creating a Digital Signature Key {#wh-fg-key-dig-sig-ex} ================================================================= ``` { "clientRequestAction": "CREATE", "keyInformation": { "provider": "nrtd", "tenant": "merchantName", "keyType": "sharedSecret", "organizationId": "merchantName" } } ``` ``` { "submitTimeUtc": "2021-03-17T06:53:06+0000", "status": "SUCCESS", "keyInformation": { "provider": "NRTD", "tenant": "merchantName", "organizationId": "merchantName", "keyId": "bdc0fe52-091e-b0d6-e053-34b8d30a0504", //ID associated with the key in the key field "key": "u3qgvoaJ73rLJdPLTU3moxrXyNZA4eo5dklKtIXhsAE=", //Base64 encoded key "keyType": "sharedSecret", "status": "Active", "expirationDate": "2022-03-17T06:53:06+0000" } ``` REST Interactive Example: Creating a Digital Signature Key {#wh-fg-key-dig-sig-dev-ex} ====================================================================================== Click this image to access the interactive code example for creating a digital signature key. The Live Console refers to this request as *Create Webhook Symmetric Key*. #### Figure: Creating a Digital Signature Key [![Image and link to the interactive code example for creating a digital signature key.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/dev-ex-create-digi-sig-key.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md#webhooks_create-new-webhooks_create-webhook-security-keys_samplerequests-dropdown_create-webhook-symmetric-key_liveconsole-tab-request-body "") Provide Your OAuth Credentials {#wh-fg-oauth-cred-intro} ======================================================== If your system uses the *OAuth* or *OAuth with JWT* security policy, you must provide your OAuth credentials to `Cybersource`. When `Cybersource` sends you webhook notifications in the future, `Cybersource` will use your OAuth credentials to access your server and deliver the notification message. > IMPORTANT > If you are only using the default *mutual trust* security policy, you do not need to provide OAuth credentials to ` Cybersource `. **OAuth** : 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 `Cybersource` services to obtain only the relevant user data without exposing the user's credentials. **OAuth with JWT** : 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. Endpoints --------- Send a POST to one of these endpoints: * **Test:** `POST ``https://apitest.cybersource.com``/kms/egress/v2/keys-sym` * **Production:** `POST ``https://api.cybersource.com``/kms/egress/v2/keys-sym` * **India Production:** `POST https://api.in.cybersource.com/kms/egress/v2/keys-sym` {#wh-fg-oauth-cred-intro_ul_kmx_mcl_b1c} Required Fields for Providing Your OAuth Credentials {#wh-fg-oauth-cred-req-fields} =================================================================================== clientRequestAction : Set to `STORE`. keyInformation.clientKeyId : Set to the OAuth client's username. keyInformation.expiryDuration : Set to `365`. keyInformation.key : Set to the client's secret key. keyInformation.keyType : Set to `oAuthClientCredentials`. keyInformation.organizationId : Set to the organization ID or merchant ID of the organization requesting the key. keyInformation.provider : Set to the organization ID that the requesting organization belongs to. keyInformation.tenant : Set to `nrtd`. Example: Providing Your OAuth Credentials {#wh-fg-oauth-cred-ex} ================================================================ ``` { "clientRequestAction": "STORE", "keyInformation": { "provider": "merchantName", "tenant": "nrtd", "keyType": "oAuthClientCredentials", "organizationId": "merchantName", "clientKeyId": "client username", "key": "client secret", "expiryDuration": "365" } } ``` ``` { "submitTimeUtc": "2022-02-18T19:49:52Z", "status": "SUCCESS", "keyInformation": { "provider": "org1", "tenant": "nrtd", "organizationId": "org1", "clientKeyId": "ef400ac1-edfe-406e-94b3-0d73be09a1a0", "keyId": "d8512fb5-1d8c-4f2d-e053-3cb8d30a764c", "key": "KTTY1LLGYR6A2LL4XZTT9W9RGCVJ5Z4XZAP6AFTRUFWLSXX0NX4N88N9EJED3BMM", "keyType": "oAuthClientCredentials", "status": "active", "expirationDate": "2023-02-18T19:49:52Z" } } ``` REST Interactive Example: Providing Your OAuth Credentials {#wh-fg-oauth-cred-dev-ex} ===================================================================================== Click this image to access the interactive code example for providing your OAuth credentials to `Cybersource`. The Live Console refers to this request as *Store oAuth Credentials*. #### Figure: Providing Your OAuth Credentials [![Image and link to the interactive code example for providing your OAuth credentials.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/dev-ex-oauth-cred.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md#webhooks_create-new-webhooks_create-webhook-security-keys_samplerequests-dropdown_store-oauth-credentials_liveconsole-tab-request-body "") Retrieve a List of Products and Events {#wh-fg-product-list-intro} ================================================================== This section describes how to retrieve a list of the products and event types that are enabled for your organization. Use this list to know which products and events that you can subscribe to. A successful response lists the enabled products and events in the productId and eventTypes.eventName fields. You can use these same fields values when you send a *create a webhook subscription* request. If the list you retrieve does not contain an expected product or event type, the product may not be enabled for your organization. Contact your account manager for more information. For a list of all the products and event types that are supported by the Webhooks `REST API`, see the [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). Endpoints --------- Send a GET request to one of these endpoints. The *{organizationId}* is your organization ID. * **Test:** `GET ``https://apitest.cybersource.com``/notification-subscriptions/v2/products/`*{organizationId}* * **Production:** `GET ``https://api.cybersource.com``/webhooks/notification-subscriptions/v2/products/`*{organizationId}* * **India Production:** `GET https://api.in.cybersource.com/notification-subscriptions/v2/products/`*{organizationId}* Example: Retrieving a List Products and Event {#wh-fg-product-list-ex} ====================================================================== ```keyword GET https://api.cybersource.com/notification-subscriptions/v2/products/{organizationId} ``` ``` [ { "productId": "terminalManagement", "eventTypes": [ { "eventName": "terminalManagement.status.update", "payloadEncryption": false }, { "eventName": "terminalManagement.assignment.update", "payloadEncryption": false }, { "eventName": "terminalManagement.reAssignment.update", "payloadEncryption": false } ] } ] ``` REST Interactive Example: Retrieving Product and Event Types {#wh-fg-product-events-dev-ex} =========================================================================================== Click this image to access the interactive code example for retrieving the product and event types enabled for your organization. #### Figure: Retrieve Product and Event Types [![Image and link to the interactive code example for retrieving the product and event types enabled for your organization.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/retrieve-product-list-dev.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_create-new-webhooks_find-products-you-can-subscribe-to "") Create a Webhook Subscription {#wh-fg-subscribe-intro} ====================================================== This section describes how to create a webhook subscription using the REST API. The request you send is dependent on your system's security policy: * Mutual trust (default) * Mutual trust and *OAuth* * Mutual trust and *OAuth with JWT* The Webhooks REST API uses the mutual trust security policy by default. In addition to mutual trust, you can also use the OAuth or OAuth JWT security policy. If you are not using OAuth security to authenticate your webhook notifications, use the default mutual trust request. Create a Webhook Subscription Using Mutual Trust {#wh-fg-subscription-mutual-api-intro} ======================================================================================= This section describes how to create webhook subscription using mutual trust. You can subscribe to multiple webhook products and event types in the same request. *Mutual trust* is the default security policy for webhooks. It is a simple authentication scheme that is included in the HTTP protocol. Mutual trust is often used in conjunction with HTTPS to provide confidentiality through encryption. 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 ""). 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. 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/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 Using Mutual Trust {#wh-fg-subscription-mutual-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-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-product-event-types.md ""). securityPolicy.securityType : Set to `KEY`. webhookUrl : Optional Fields for Subscribing to Webhooks Using Mutual Trust {#wh-fg-subscription-mutual-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/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 Mutual Trust {#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": "product.name", "eventTypes": [ "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 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** {#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/new-documentation/documentation/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 "") 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 `Cybersource` services to obtain only the relevant user data without exposing the user's credentials. 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. 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/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 {#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/cybs/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/cybs/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/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 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/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 {#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.cybersource.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 `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** {#wh-fg-subscription-oauth-dev-ex} ========================================================================================================== Click this image to access the interactive code example for creating a webhook subscription using OAuth. #### Figure: Create a Webhook Subscription Using OAuth [![Image and link to the interactive code example for creating a webhook subscription using OAuth.](/content/dam/new-documentation/documentation/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 "") 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). 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. 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/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-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-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 : 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/new-documentation/documentation/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 "") Examples of all Products and Event Types {#wh-fg-product-ex-intro} ================================================================== This section shows examples of creating a subscription with every supported product and event type. Use these examples as references for how to properly format the product IDs and event types when you create a subscription. Request Examples for Creating a Subscription for all Products and Event Types {#wh-fg-product-payments-intro} ============================================================================================================= **Alternative Payments Request** ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "alternativePaymentMethods", "eventTypes": [ "payments.payments.updated" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` **`eCheck` Request** ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "eCheck", "eventTypes": [ "payments.credits.accepted", "payments.credits.failed", "payments.payments.accepted", "payments.payments.failed", "payments.voids.accepted", "payments.voids.failed" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` **`Fraud Management Essentials` Request** ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "fraudManagementEssentials", "eventTypes": [ "risk.casemanagement.decision.accept", "risk.casemanagement.addnote", "risk.profile.decision.reject", "risk.casemanagement.decision.reject", "risk.profile.decision.monitor", "risk.profile.decision.review" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` **Invoicing Request** ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "customerInvoicing", "eventTypes": [ "invoicing.customer.invoice.send", "invoicing.customer.invoice.cancel", "invoicing.customer.invoice.paid", "invoicing.customer.invoice.partial-payment", "invoicing.customer.invoice.reminder", "invoicing.customer.invoice.overdue-reminder" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` **Payments Request** ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "payments", "eventTypes": [ "payments.capture.status.accepted", "payments.capture.status.updated" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` **`Pay by Link` Merchant Request** ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "payByLink", "eventTypes": [ "payByLink.merchant.payment" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` **`Pay by Link` Partner Reseller Request** ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "payByLink", "eventTypes": [ "payByLink.customer.payment" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` **Recurring Billing Request** ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "recurringBilling", "eventTypes": [ "rbs.subscriptions.charge.failed", "rbs.subscriptions.charge.pre-notified", "rbs.subscriptions.charge.created" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` **`Token Management Service` Request** ``` { "name": "My Custom Webhook", "description": "Sample Webhook from Developer Center", "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>", "products": [ { "productId": "tokenManagement", "eventTypes": [ "tms.networktoken.updated", "tms.networktoken.provisioned," "tms.networktoken.binding" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "securityPolicy": { "securityType": "KEY" } } ``` Optional Set-Up Tasks {#wh-fg-optional-intro} ============================================= This section describes optional set-up tasks that you can complete while or after creating a webhook subscription. These tasks are optional and are not required to successfully set-up webhook subscriptions. * Include a health check URL to enable `Cybersource` to monitor your server's status for reliability. * Validate the integrity of a webhook notification. * Set up a retry policy for how to receive notifications when your server URL is initially unresponsive. Webhook Health Check URL and Automatic Revalidation {#wh-fg-subscription-health-check-url} ========================================================================================== When you create a webhook subscription, `Cybersource` recommends that you include a health check URL in the request. Including a health check URL enables `Cybersource` to monitor your server's status for reliability. When `Cybersource` detects that your health check URL is unresponsive, notification deliveries are withheld until your health check URL becomes responsive again. A health check URL ensures that you do not miss any notifications. To add a health check URL to your *create a 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` to enable `Cybersource` to withhold notifications for periods when your server becomes unresponsive. Automatic Activation -------------------- After you successfully create or update a subscription, `Cybersource` pings your health check URL within 5---10 minutes. If `Cybersource` receives a response, the subscription status automatically becomes `ACTIVE` and notifications are delivered. When `Cybersource` does not receive a response, your subscription status remains `SUSPENDED` until `Cybersource` receives a response. If you did not include a health check URL when you created the subscription, `Cybersource` 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 [Activate a Webhook Subscription](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscription-manage-intro/wh-fg-subscription-manage-activate-intro.md ""). #### Figure: Webhook Automatic Activation ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/webhooks-subscription-cybs-600x400.svg/jcr:content/renditions/original) Automatic Revalidation ---------------------- After the subscription's initial activation, `Cybersource` continues to monitor your server status. If `Cybersource` detects that your server is unavailable, your subscription status automatically updates to `SUSPENDED`, and notifications are withheld. When `Cybersource` detects that your server is available again, your subscription status automatically updates to `ACTIVE`, and all withheld notifications are delivered. Configure the Retry Policy {#wh-fg-optional-retry} ================================================== If your webhook URL or health check URL are unresponsive, `Cybersource` resends the webhook notifications according to the subscription's *retry policy*. All subscriptions are created with a default retry policy. You can configure the default retry policy when you create a subscription or update the webhook subscription. To configure a subscription's retry policy, include these required fields in the *create a subscription* request or an *update a subscription* request: retryPolicy.deactivateFlag : Set to one of these possible values: : * `false`: Notifications are *not* withheld when your webhook URL or health check URL are unresponsive. This is the default value. * `true`: Notifications are withheld when your webhook URL or health check URL are unresponsive, and the subscription status updates to `SUSPENDED`. When the URLs become responsive again, the withheld notifications are sent and the subscription status updates to `ACTIVE`. retryPolicy.firstRetry : The number of minutes before the notification is resent. The default value is `1`. retryPolicy.interval : The number of minutes between each retry attempt. The default value is `1`. retryPolicy.numberOfRetries : The number of retry attempts. The default value is `3`. retryPolicy.repeatSequenceCount : The number of times to repeat the retry sequence. The default value is `0`. retryPolicy.repeatSequenceWaitTime : The number of minutes between each repeat sequence. The default value is `0`. Example: Retry Policy in a Subscription Request {#wh-fg-optional-retry-example} =============================================================================== This excerpt example shows how to format a retry policy in a request. ``` "retryPolicy": { "firstRetry": "1", "interval": "1", "numberOfRetries": "3", "deactivateFlag": "false", "repeatSequenceCount": "0", "repeatSequenceWaitTime": "0" } ``` Validate a Webhook Notification {#wh-fg-optional-validate-intro} ================================================================ You can verify that the webhook notifications that you receive are from `Cybersource`. Verifying your webhook notifications validates their integrity and helps prevent replay attacks. When you receive a webhook notification from `Cybersource`, it contains a digital signature. You can configure your system to compare the notification's digital signature to the digital signature you created. If both of the digital signatures match, the notification is validated. You must complete these tasks to validate the webhook notifications that you receive: 1. You create a digital signature key by sending a *create a digital signature key* request to `Cybersource`. You may have already completed this requirement while setting up your first webhook subscription. For more information, see [Create a Digital Signature Key](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-key-dig-sig-intro.md ""). 2. You extract the digital signature from the digital signature key that you created. 3. You configure your system to compare your digital signature to the digital signatures in the notifications that you receive. A webhook notification is valid if the notification's digital signature matches your digital signature. Digital Signature Format {#wh-fg-optional-validate-sig-format} ============================================================== When you receive a webhook notification from `Cybersource`, it contains a `v-c-signature` header in this format: ``` v-c-signature: t=1617830804768;keyId=bf44c857-b182-bb05-e053-34b8d30a7a72;sig=CzHY47nzJgCSD/BREtSIb+9l/vfkaaL4qf9n8MNJ4CY="; ``` The header contains these three parameters concatenated with semicolons: * t: The timestamp at which the digital signature key was created. * keyId: The digital signature key ID. * sig: The digital signature. It is encrypted using the HMAC-SHA256 algorithm. How to Create Your Digital Signature ------------------------------------ Create your own digital signature using the above format. Use the key values you received from creating a digital signature key in your digital signature. When you request the creation of a digital signature key, the response contains a *digital signature key* and a *key ID* . The digital signature key is in the keyInformation.keyinformation.key field and the key ID is in the keyInformation.keyinformation.keyId field. Validating a Notification {#wh-fg-optional-validate} ==================================================== Follow these steps to validate the integrity of your webhook notifications. 1. Separate the signature parameters with a semicolon (;) and extract the `t`, `keyId`, and `sig` values. 2. Use the `keyId` value to fetch the digital signature key. 3. Generate the payload by concatenating the timestamp with a period (.) and the payload from the body of the notification. 4. Use the SHA256 algorithm to encrypt the generated payload from Step 3 using the key from Step 2. 5. Verify that the encrypted value matches the value in `sig` parameter. Example: Validating a Notification {#wh-fg-optional-validate-ex} ================================================================ This is an example of a system script that validates webhook notifications by the merchant's digital signature with the webhook notification's signature. Use this example as a reference for how to potentially configure your system. ``` import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.util.Arrays; import java.util.Base64; public class Validator { public static void main(String[] args) { // Sample signature header String signatureHeader = "v-c-signature: t=1617830804768;keyId=bf44c857-b182-bb05-e053-34b8d30a7a72;sig=CzHY47nzJgCSD/BREtSIb+9l/vfkaaL4qf9n8MNJ4CY="; String payload = "this is a decrypted payload"; // Convert the received signatureHeader into timestamp, keyId, and signature. DigitalSignature companySignature = new DigitalSignature(signatureHeader); // Check if the timestamp is within tolerance. if (companySignature.isValidTimestamp()) { // Client regenerates their signature using the timestamp from header and received payload. byte[] signature = regenerateSignature(companySignature.getTimestamp(), payload); // Check if the generated signature is same as signature received in header. if (isValidSignature(signature, companySignature.getSignature())) { System.out.println("Success - Signature is valid"); } else { System.out.println("Error - Signatures do not match"); } } else { System.out.println("Error - timestamp is outside of tolerance level"); } } /** * Compute HMAC with the SHA256 hash function. * key is your private key. * message is timestamp.payload. * @return */ public static byte[] regenerateSignature(long timestamp, String message) { String timestampedMessage = timestamp + "." + message; String key = getSecurityKey(); // Generate the hash using key and message. return calcHmacSHA256(Base64.getDecoder().decode(key), timestampedMessage.getBytes(StandardCharsets.UTF_8)); } /** * A mechanism to fetch the security key using keyId from a source. We're using Base64encoded version of (test_key). * @return */ private static String getSecurityKey() { return "dGVzdF9rZXk="; //test_key } /** * Generate SHA256 using secretKey and a message. * Sample Hmacgenerator to test: https://8gwifi.org/hmacgen.jsp * @param secretKey * @param message * @return */ private static byte[] calcHmacSHA256(byte[] secretKey, byte[] message) { byte[] hmacSha256 = null; try { Mac mac = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey, "HmacSHA256"); mac.init(secretKeySpec); hmacSha256 = mac.doFinal(message); } catch (Exception e) { throw new RuntimeException("Failed to calculate hmac-sha256", e); } return hmacSha256; } /** * Compare the Base64 decoding of the signature with the signature received in the header. * Sample encoder/decoder to test: * https://www.base64encode.org/ * https://www.base64decode.org/ * @param bankSignature * @param companySignature * @return */ private static boolean isValidSignature(byte[] bankSignature, String companySignature) { return Arrays.equals(bankSignature, Base64.getDecoder().decode(companySignature)); } } import java.time.Clock; public class DigitalSignature { private long timestamp; private String keyId; private String signature; public DigitalSignature(String digitalSignature) { try { //split the header by space. first part is the key "v-c-signature" second part is the actual signature       String signature = digitalSignature.split(" ")[1]; //separate the actual signature by semicolon. this creates 3 parts (timestamp, keyId, sig) String[] signatureParts = signature.split(";"); //timestamp section is the first block. split timestamp section by = sign and actual timestamp is in the second block this.timestamp = Long.parseLong(signatureParts[0].split("=")[1]); //keyId section is the second block. split keyId section by = sign and actual keyId is in the second block this.keyId = signatureParts[1].split("=")[1]; //digital signature is the third block. split digital signature by = sign and actual signature is in the second block. This is Base64 encoded this.signature = signatureParts[2].split("=")[1]; if unable to format exactly like the above then would recommend the following edit: /* split the header by space. first part is the key "v-c-signature" second part is the actual signature */       String signature = digitalSignature.split(" ")[1]; /* separate the actual signature by semicolon. this creates 3 parts (timestamp, keyId, sig) */ String[] signatureParts = signature.split(";"); /* timestamp section is the first block. split timestamp section by = sign and actual timestamp is in the second block */ this.timestamp = Long.parseLong(signatureParts[0].split("=")[1]); /* keyId section is the second block. split keyId section by = sign and actual keyId is in the second block */ this.keyId = signatureParts[1].split("=")[1]; /* digital signature is the third block. split digital signature by = sign and actual signature is in the second block. This is Base64 encoded */ this.signature = signatureParts[2].split("=")[1]; } catch (Exception e) { System.out.println("Invalid digital signature format"); } } public long getTimestamp() { return timestamp; } public void setTimestamp(long timestamp) { this.timestamp = timestamp; } public String getKeyId() { return keyId; } public void setKeyId(String keyId) { this.keyId = keyId; } public String getSignature() { return signature; } public void setSignature(String signature) { this.signature = signature; } /** * Using a tolerance of 60 mins * Compute the current time in UTC and make sure the timestamp was generated within the tolerance period. * UTC millis generator to test: https://currentmillis.com/ * * @return */ public boolean isValidTimestamp() { long tolerance = 60 * 60 * 1000L; //60 mins // return Clock.systemUTC().millis() - timestamp < tolerance; // Enable this if you want timestamp validation. return true; } } ``` Webhook Notification Header and Message Body Descriptions {#wh-fg-notification-format} ====================================================================================== Each webhook notification for an event update contains headers and a message body with fields. This section describes the possible fields and values you can receive in a notification. Notification Headers -------------------- These headers are sent in every notification. Some headers contain duplicate information from the fields in the message body. `V-C-signature` : The digital signature, which you can use to validate the security of the notification. `V-C-event-type` : The type of event that generated the notification. `V-C-organization-id` : The identifier of the organization that is subscribed to the notification. `V-C-product-name` : The name of the product for which the event occurred. `V-C-request-type` : The indicator of whether the notification is new or a retry attempt. `V-C-retry-count` : The number of times the notification was resent. `V-C-transaction-trace-id` : The identifier of the notification attempt. Every retry attempt has a unique transaction trace ID. The notification ID remains the same. `v-c-webhook-id` : The identifier of the webhook subscription that generated the notification. Notification Message Body ------------------------- The message body contains fields associated with the notification and the payload of the event that generated the notification. webhookId : The identifier of the webhook subscription that generated the notification. transactionTraceId : The identifier of the notification attempt. Every retry attempt has a unique transaction trace ID. The notification ID remains the same. productId : The identifier of the product that generated the event. organizationId : The identifier of the organization that is subscribed to the notification. eventType : The type of event that generated the notification. eventDate : The timestamp of when the event occurred. payload : The data generated by the event. requestType : The indicator of whether the notification is new or a retry attempt. Example: Webhook Notification {#wh-fg-oauth-jwt-notification-payload-ex} ======================================================================== This is an example of a received webhook notification. Use this example to know what your system can expect when you receive a notification. Invoicing Webhook Notification ```keyword POST /test HTTP/1.1 Host: invoicetest.example.com Content-Length: 1647 Content-Type: application/json User-Agent: Vert.x-WebClient/3.9.8 V-C-Event-Type: invoicing.customer.invoice.send V-C-Organization-Id: invoicetest V-C-Product-Name: customerInvoicing V-C-Request-Type: NEW V-C-Retry-Count: 0 V-C-Signature: t=168506218354;keyId=facdaf45-db00-233c-e053-5a588d0a743a;sig=kJgSHwHrRgUmXJdaSSqtPVzOTMlV3SW90WAFIfPj4XA= V-C-Transaction-Trace-Id: 8c01a8e9b3334d19528d9b69a21fe797ebaf8dd3dee52f422dd699af26bd866-0 V-C-Webhook-Id: fc8a9385-723e8e28-e053-a2588e0a536d { "notificationId":"fc8f1cae-1232-5dd-e053-a0588e0a5eeb", "retryNumber":0, "eventType":"invoicing.customer.invoice.send", "eventDate":"2023-05-25T17:49:40.309-07:00", "webhookId":"fc8a9385-723e-8e28-e053-a2588e0a536d", "payloads":[ { "data":{ "merchantZip":"12345", "thankYou":"Thank you for your business!", "subject":"You've received an invoice 202203789 from Company, Inc.", "dueDate":"2023-05-25", "link":"Click the link below to view and pay the invoice.", "body":"You have a new invoice from Company, Inc. for 102.00 ALL due on 2023-05-25.", "merchantState":"OH", "merchantName":"Company, Inc.", "button":"VIEW AND PAY INVOICE", "invoiceBalance":"102.00", "merchantAddress2":" ", "invoiceNumber":"20220389", "payerName":"Firstname Lastname", "customMessage":"Thank you for your business. By clicking the view and pay invoice you agree to the terms and conditions here: https://paymenttermsandconditions.example.com", "currency":"ALL", "merchantCity":"Placeville", "emailTo":"Person@example.com", "eventType":"invoicing.customer.invoice.send", "balanceAmount":"102.00", "organizationID":"invoicetest", "merchantPhone":"321-321-3211", "emailLanguage":"en-us", "invoiceUrl":"https://businesscentertest.cybersource.com/ebc2/invoicing/payInvoice/u2wJqUKII4FsqtIrZx51lUuvYr5Msz23nqIx12xqJhs7wqT6Th2mJcDOYHSC5hE?version=v2.1", "merchantAddress":"39 E. Road St", "correlationID":"dceb3ce-d787-453c-84a3-ce33b141cc76", "hello":"Hello Person," }, "preferences":{ "contacts":[ { "firstName":"Invoicing", "lastName":"Email", "contact":"person@example.com", "type":"EMAIL" } ] }, "organizationId":"invoicetest", "metadata":{ "from.displayName":"Company, Inc.", "reply.email":"noreply@example.com", "sentBy":"Invoice" } } ] } ``` Create a Sample Webhook Subscription {#wh-fg-trig-tms-webhook} ============================================================== Follow these steps to create a sample webhook subscription and then trigger a test webhook notification. This sample subscription uses the `Token Management Service` (`TMS`). IMPORTANT > You must first confirm that your organization ID is enabled for ` TMS ` and that a ` TMS ` vault is set up. For assistance, contact ` Cybersource ` Customer Support. 1. Create a `TMS` webhook subscription for your organization ID using this endpoint: ` POST ``https://apitest.cybersource.com``/notification-subscriptions/v2/webhooks` Set the productId field to `tokenManagement` and the eventTypes field to `tms.networktoken.provisioned`. This example creates a webhook subscription using Mutual trust, which is the default security policy. ``` { "name": "TMS Webhook", "description": "Sample TMS Webhook from Developer Center", "organizationId": "organizationId", "productId": "tokenManagement", "eventTypes": [ "tms.networktoken.provisioned" ], "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient", "healthCheckUrl": "https://MyWebhookServer.com:8443/simulateClientHealthCheck", "notificationScope": "SELF", "retryPolicy": { "algorithm": "ARITHMETIC", "firstRetry": 1, "interval": 1, "numberOfRetries": 3, "deactivateFlag": "false", "repeatSequenceCount": 0, "repeatSequenceWaitTime": 0 }, "securityPolicy": { "securityType": "KEY", "proxyType": "external" } } ``` {#wh-fg-trig-tms-webhook_codeblock_fpt_lv2_syb} 2. Go to the [Create an Instrument Identifier](https://developer.cybersource.com/api-reference-assets/index.md#token-management_instrument-identifier_create-an-instrument-identifier "") section in the API Field Reference. 3. Click the **Configuration** tab. 4. In the Sample Request drop-down menu, choose Create Instrument Identifier using a Card and Create Network Token: ![](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/wh-fg-tms-create-ii.png/jcr:content/renditions/original) 5. Set the card.number field to a test PAN. If you need a test PAN, contact `Cybersource` customer support. Send the request to this endpoint: `POST ``https://apitest.cybersource.com``/tms/v1/instrumentidentifiers`{#wh-fg-trig-tms-webhook_codeblock_fkq_ykl_5yb} ``` { "type": "enrollable card", "card": { "number": "411111111111XXXX", // Replace the ‘X’s with 1 "expirationMonth": "12", "expirationYear": "2031" } } ``` {#wh-fg-trig-tms-webhook_codeblock_rbx_fhf_syb} IMPORTANT > A test PAN can only have one associated instrument identifier. If you need to test multiple webhook notifications, delete the instrument identifier created for that PAN before using the *Delete an Instrument Identifier API*. 6. Click Send. After you receive a successful response, your system should receive a webhook event notification. For an example of a complete webhook notification, including the header and payload information, see [Example: Webhook Notification](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-notification-format.md ""). Manage Webhook Subscriptions Requests {#wh-fg-subscription-manage-intro} ======================================================================== This section describes how to manage your webhook subscriptions using the REST API. These follow-on requests require the webhook subscription ID. After you set up a webhook subscription, you can manage your subscription using these requests: * Retrieve the details of a subscription * Retrieve a list of subscriptions by product and event * Update a subscription * Delete a subscription * Verify a subscription's configuration * Activate a subscription * Deactivate a subscription Retrieve the Details of a Webhook Subscription {#wh-fg-subscription-manage-get-intro} ===================================================================================== This section describes how to retrieve the details of a webhook subscription, such as the subscription status, which organizations are receiving the notifications, and other useful details. This request requires the webhook subscription ID. The subscription ID is in the webhookId response field from the *create a webhook subscription* request. Endpoints --------- Send a GET request to this endpoint. The *`{webhookId}`* is the webhook subscription ID. * **Test:** `GET ``apitest.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}* * **Production:** `GET ``api.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}* * **India Production:** `GET https://api.in.cybersource.com/notification-subscriptions/v2/webhooks/`*{webhookId}* Example: Retrieving the Details of a Webhook Subscription {#wh-fg-subscription-manage-get-ex} ============================================================================================= ```keyword GET https://apitest.cybersource.com/notification-subscriptions/v1/webhooks/ddb9bced-c3e3-1b1d-e053-9c588e0a3c42 ``` ``` { "organizationId": "organizationId", "productId": "terminalManagement", "eventTypes": [ "terminalManagement.assignment.update" ], "webhookId": "ddb9bced-c3e3-1b1d-e053-9c588e0a3c42", "webhookUrl": "https://MyWebhookServer.com:443/simulateClient", "healthCheckUrl": "https://MyWebhookServer.com:443/simulateClientHealthCheck", "createdOn": "2022-04-28 15:39:56.931", "status": "SUSPENDED", "retryPolicy": { "algorithm": "ARITHMETIC", "firstRetry": 1, "interval": 1, "numberOfRetries": 3, "deactivateFlag": false, "repeatSequenceCount": 0, "repeatSequenceWaitTime": 0 }, "securityPolicy": { "securityType": "KEY", "digitalSignatureEnabled": "yes" }, "version": "3", "deliveryType": "nrtdCentral", "notificationScope": "DESCENDANTS" } ``` Response Codes {#wh-fg-subscription-manage-get-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 ""). REST Interactive Example: Retrieve the Details of a Webhook Subscription {#wh-fg-subscription-manage-get-dev-ex} ================================================================================================================ Click this image to access the interactive code example for retrieving the details of a webhook subscription. #### Figure: Retrieve the Details of a Webhook Subscription [![Image and link to the interactive code example for retrieving the details of a webhook subscription.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/dev-ex-get-details.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_manage-webhooks_get-details-on-a-single-webhook "") Retrieve all of an Organization's Subscriptions {#wh-fg-subscription-manage-get-list-intro} =========================================================================================== This section describes how to retrieve a list of the webhook subscriptions that an organization is subscribed to. This request requires you to include the organization ID in the endpoint as a query parameter. You have the option to include a product ID and event type as additional query parameters. If you include any of the optional query parameters, you must concatenate them by separating each parameter with the ampersand character (`&`). Endpoints --------- Send a GET request to one of these endpoints. The *`{organization.id}`* is the organization ID or merchant ID. * **Test:** `GET ``https://apitest.cybersource.com``/notification-subscriptions/v2/webhooks?organizationId=`*{organization.id}* * **Production:** `GET ``https://api.cybersource.com``/notification-subscriptions/v2/webhooks?organizationId=`*{organization.id}* * **India Production:** `GET https://api.in.cybersource.com/notification-subscriptions/v2/webhooks?organizationId=`*{organization.id}* Required Query Parameters for Retrieving all of an Organization's Subscriptions {#wh-fg-subscription-manage-get-list-req-fields} ================================================================================================================================ eventType : Set to an event type. For a list of event types, see [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). organizationId : Set to your organization ID or merchant ID. productId : Set to a product ID. For a list of product IDs, see [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). Optional Query Parameters for Retrieving all of an Organization's Subscriptions {#wh-fg-subscription-manage-get-list-opt-fields} ================================================================================================================================ eventType : Set to an event type that corresponds to the chosen product ID. For a list of event types, see [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). productId : Set to a product ID. For a list of product IDs, see [Supported Products and Event Types](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-product-event-types.md ""). Example: Retrieving all of an Organization's Subscriptions {#wh-fg-subscription-manage-get-list-ex} =================================================================================================== ```keyword GET https://apitest.cybersource.com/notification-subscriptions/v2/webhooks?organizationId=organization123&productId=tokenManagement&eventType=tms.networktoken.provisioned ``` Response Codes {#wh-fg-subscription-manage-get-list-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 ""). REST Interactive Example: Retrieving all of an Organization's Subscriptions {#wh-fg-subscription-manage-get-list-dev-ex} ======================================================================================================================== Click this image to access the interactive code example for retrieving an organization's subscription using the product and event. #### Figure: Retrieve an Organization's Subscriptions Using the Product and Event [![Image and link to the interactive code example for retrieving an organization's subscription using the product and event.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/dev-ex-get-list.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_manage-webhooks_get-details-on-all-created-webhooks "") Update a Webhook Subscription {#wh-fg-subscription-manage-patch-intro} ====================================================================== This section describes how to update a webhook subscription, such as updating the notification scope, health check URL, or retry policy. Include only the fields that you want to update in your request. This request requires the webhook subscription ID. The subscription ID is in the webhookId response field from the *create a webhook subscription* request. Endpoints --------- Send a PATCH request to one of these endpoints. The *`{webhookId}`* is the webhook subscription ID. * **Test:** `PATCH ``apitest.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}* * **Production:** `PATCH ``api.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}* * **India Production:** `PATCH https://api.in.cybersource.com/notification-subscriptions/v2/webhooks/`*{webhookId}* Optional Fields for Updating a Webhook Subscription {#wh-fg-subscription-manage-patch-opt-fields} ================================================================================================= deactivateflag : Required if the healthCheckUrl field is present. : Set to `true` to automatically activate the subscription. description : 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 ""). 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-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-product-event-types.md ""). 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 ""). securityPolicy.config.additionalConfig.aud : securityPolicy.config.additionalConfig.client_id : securityPolicy.config.additionalConfig.keyId : securityPolicy.config.additionalConfig.scope : securityPolicy.config.oAuthUrl : webhookUrl : Example: Updating a Webhook Subscription {#wh-fg-subscription-manage-patch-ex} ============================================================================== ``` { "name": "My Sample Webhook", "description": "Sample decision manager webhook reject event.", "products": [ { "productId": "decisionManager", "eventTypes": [ "risk.profile.decision.reject" ] } ], "webhookUrl": "https://MyWebhookServer.com:8443:/simulateClient", "healthCheckUrl": "https://MyWebhookServer.com:8443:/simulateClientHealthCheck", "notificationScope": { "scope": "CUSTOM" } } ``` Response Codes {#wh-fg-subscription-manage-patch-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 ""). REST Interactive Example: Updating a Webhook Subscription {#wh-fg-subscription-manage-patch-dev-ex} =================================================================================================== Click this image to access the interactive code example for updating a webhook subscription. #### Figure: Updating a Webhook Subscription [![Image and link to the interactive code example for updating a webhook subscription.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/dev-ex-patch.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_manage-webhooks_update-a-webhook-subscription "") Delete a Webhook Subscription {#wh-fg-subscription-manage-delete-intro} ======================================================================= This section describes how to delete a webhook subscription. Deleting a webhook subscription does not delete the history of webhook notifications. This request requires the webhook subscription ID. The subscription ID is in the webhookId response field from the *create a webhook subscription* request. Endpoints --------- Send a DELETE request to one of these endpoints. The *`{webhookId}`* is the webhook subscription ID. * **Test:** `DELETE ``apitest.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}* * **Production:** `DELETE ``api.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}* * **India Production:** `DELETE https://api.in.cybersource.com/notification-subscriptions/v2/webhooks/`*{webhookId}* Example: Deleting a Webhook Subscription {#wh-fg-subscription-manage-delete-ex} =============================================================================== ```keyword DELETE https://apitest.cybersource.com/notification-subscriptions/v2/webhooks/b555a545-58a9-47c7-aef9-10a8e17f201a ``` ``` { "status": "successfully deleted" } ``` Response Codes {#wh-fg-subscription-manage-delete-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 ""). REST Interactive Example: Deleting a Webhook Subscription {#wh-fg-subscription-manage-delete-dev-ex} ==================================================================================================== Click this image to access the interactive code example for deleting a webhook subscription. #### Figure: Deleting a Webhook Subscription [![Image and link to the interactive code example for deleting a webhook subscription.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/dev-ex-delete.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_manage-webhooks_delete-a-webhook-subscription "") Verify a Webhook Subscription's Configuration {#wh-fg-subscription-manage-test-intro} ===================================================================================== This section describes how to test if a webhook subscription is configured correctly. Use this request to verify that the details you are expecting in the webhook notification are included, such as the notification message and the product and event types. A successful response includes the expected notification message and the product and event type. Only the first event type in your subscription is listed in the eventType response field. This request requires the webhook subscription ID. The subscription ID is in the webhookId response field from the *create a webhook subscription* request. > IMPORTANT > **This endpoint uses the ` /v1/ ` path segment.** Endpoints --------- Send a POST request to one of these endpoints. The *`{webhookId}`* is the webhook subscription ID. * **Test:** `POST ``apitest.cybersource.com``/notification-subscriptions/v1/webhooks/`*{webhookId}* * **Production:** `POST ``api.cybersource.com``/notification-subscriptions/v1/webhooks/`*{webhookId}* * **India Production:** `POST https://api.in.cybersource.com/notification-subscriptions/v1/webhooks/`*{webhookId}* Example: Verifying a Webhook Subscription's Configuration {#wh-fg-subscription-manage-test-ex} ============================================================================================== Request ```keyword POST https://apitest.cybersource.com/notification-subscriptions/v1/webhooks/17915c64-73d9-5475-e063-7cb8d30a8089 ``` Response to a Successful Request ``` { "eventDate": "2024-05-08T16:15:23", "eventType": "tms.networktoken.updated", "organizationId": "npr_gpn", "payloads": { "testPayload": { "message": "Yay! Your webhook integration worked! This is only a test and an example of what a webhook message payload looks like. Thank you for using our test feature." } }, "productId": "tokenManagement", "requestType": "NEW", "retryNumber": "0", "transactionTraceId": "ddd8883c-f14d-48af-bd35-ff9b4a51ca35", "webhookId": "17915c64-73d9-5475-e063-7cb8d30a8089" } ``` Response Codes {#wh-fg-subscription-manage-test-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 ""). REST Interactive Example: Verifying a Webhook Subscription's Configuration {#wh-fg-subscription-manage-test-dev-ex} =================================================================================================================== Click this image to access the interactive code example for testing a webhook subscription configuration. #### Figure: Testing a Webhook Subscription Configuration [![Image and link to the interactive code example for testing a webhook subscription configuration.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/dev-ex-test.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_manage-webhooks_test-a-webhook-configuration "") Activate a Webhook Subscription {#wh-fg-subscription-manage-activate-intro} =========================================================================== This section describes how to activate a webhook subscription. This request requires the webhook subscription ID. The subscription ID is in the webhookId response field from the *create a webhook subscription* request. Endpoints {#wh-fg-subscription-manage-activate-intro_endpoint-status} --------------------------------------------------------------------- Send a PUT request to one of these endpoints. The *`{webhookId}`* is the webhook subscription ID. * **Test:** `PUT ``apitest.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}*`/status` * **Production:** `PUT ``api.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}*`/status` * **India Production:** `PUT https://api.in.cybersource.com/notification-subscriptions/v2/webhooks/`*{webhookId}*`/status` Example: Activate a Webhook Subscription {#wh-fg-subscription-manage-activate-ex} ================================================================================= Request ```keyword PUT https://apitest.cybersource.com/notification-subscriptions/v2/webhooks/ddb9bced-c3e3-1b1d-e053-9c588e0a3c42 ``` Response to a Successful Request ``` { "status": "ACTIVE" } ``` Response Codes {#wh-fg-subscription-manage-activate-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 ""). REST Interactive Example: Activating a Webhook Subscription {#wh-fg-subscription-manage-activate-dev-ex} ======================================================================================================== Click this image to access the interactive code example for activating a webhook subscription. #### Figure: Activating a Webhook Subscription [![Image and link to the interactive code example for activating a webhook subscription.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/dev-ex-status.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_manage-webhooks_update-a-webhook-status "") Deactivate a Webhook Subscription {#wh-fg-subscription-manage-deactivate-intro} =============================================================================== This section describes how to deactivate a webhook subscription. This request requires the webhook subscription ID. The subscription ID is in the webhookId response field from the *create a webhook subscription* request. Endpoints --------- Send a PUT request to one of these endpoints. The *`{webhookId}`* is the webhook subscription ID. * **Test:** `PUT ``apitest.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}*`/status` * **Production:** `PUT ``api.cybersource.com``/notification-subscriptions/v2/webhooks/`*{webhookId}*`/status` * **India Production:** `PUT https://api.in.cybersource.com/notification-subscriptions/v2/webhooks/`*{webhookId}*`/status` Example: Deactivate a Webhook Subscription {#wh-fg-subscription-manage-deactivate-ex} ===================================================================================== Request ```keyword PUT https://apitest.cybersource.com/notification-subscriptions/v2/webhooks/ddb9bced-c3e3-1b1d-e053-9c588e0a3c42 ``` Response to a Successful Request ``` { "status": "INACTIVE" } ``` Response Codes {#wh-fg-subscription-manage-deactivate-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 ""). REST Interactive Example: Deactivating a Webhook Subscription {#wh-fg-subscription-manage-deactivate-dev-ex} ============================================================================================================ Click this image to access the interactive code example for deactivating a webhook subscription. #### Figure: Deactivating a Webhook Subscription [![Image and link to the interactive code example for deactivating a webhook subscription.](/content/dam/new-documentation/documentation/en-us/topics/payments-processing/payment-services/webhooks/images/dev-ex-status.png/jcr:content/renditions/original)](https://developer.cybersource.com/api-reference-assets/index.md?stage=pilot#webhooks_manage-webhooks_update-a-webhook-status "") Troubleshooting Webhook Subscriptions {#wh-fg-subscription-troubleshooting} =========================================================================== If you created a webhook subscription but are not receiving notifications: * Verify that the digital signature key you created includes the correct organization ID. You can verify the organization ID by locating it in the response for creating the digital signature key. If the key is configured with the wrong organization ID, send a request for a new digital signature key using the correct organization ID. * Verify that your server and the endpoint URL for the webhook are working and are configured correctly. * Verify that the notification scope of the subscription is configured to send notifications to the correct organization. You can retrieve the webhook details to verify that the organization is listed in the organizationId response field. For more information, see [Retrieve the Details of a Webhook Subscription](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscription-manage-intro/wh-fg-subscription-manage-get-intro.md ""). If the organization is not in the notification scope, you must update the webhook subscription. For more information, see [Update a Webhook Subscription](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscription-manage-intro/wh-fg-subscription-manage-patch-intro.md ""). * Verify that the subscription status is `ACTIVE`. You can do this by retrieving the webhook details. For more information, see [Retrieve the Details of a Webhook Subscription](/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-subscription-manage-intro/wh-fg-subscription-manage-get-intro.md ""). If the webhook is not set to the `ACTIVE` status: * Verify that your subscription is configured with a health check URL. If it is not, update the subscription with a correct URL. You must also verify that the URL is working and is configured to accept GET and POST requests. 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 ""). * Verify that the webhook URL and health check URL contain hypertext transfer protocol secure (HTTPS). For example: ``` "webhookUrl": "https://MyWebhookServer.com:443/simulateClient" "healthCheckUrl": "https://MyWebhookServer.com:443/simulateClientHealthCheck" ``` Meta Key Creation and Management {#keys-meta-intro} =================================================== A meta key is a specialized API key that a portfolio or merchant account user can create for the purposes of processing transactions on behalf of multiple of their transacting MID accounts. Meta keys are useful for organizations whose transacting MID users do not manage or store their own individual API keys. Instead of having to create and assign a unique API key for each of your transacting MIDs, you can create and assign a single meta key to dozens or hundreds of your transacting MIDs simultaneously. IMPORTANT Transacting MIDs cannot generate meta keys. For security reasons, do not give a meta key to your transacting MID users. Meta keys are available for these APIs: * REST * Simple Order API * SOAP * SCMP {#keys-meta-intro_ul_pbd_hts_55b} When you are logged in to a portfolio account or merchant account in the `Business Center`, you can assign a meta key to a static subset of transacting MIDs or to all current and future transacting MIDs. If you choose to assign a meta key to only a subset of transacting MIDs, you can reassign the key later to all current and future transacting MIDs. When using a meta key, the portfolio account or merchant account user submits a transaction on behalf of the transacting MID. These processed transactions are recognized as belonging to the transacting MID. Searching for or reporting on the transactions are performed at the transacting MID level. All three account types can process follow-on transactions to the initial transaction, such as a capture or refund. Access to creating and managing meta keys is automatically enabled for all organizations. You can disable the meta key feature to not allow portfolio or merchant account users to generate meta keys or process transactions using meta keys. > WARNING When a meta key expires, it expires for all transacting MIDs to which it is assigned. All transactions using that meta key will fail. Careful monitoring is necessary to track meta key expiration dates. You must create and assign a new key before the previous key expires. The length of time after which a key expires depends on the API for which the key was created. Read the instructions for the API key you will use. Hierarchy of Meta Keys ---------------------- In this diagram, if the portfolio user assigns a meta key to all of the transacting MIDs, every transacting MID in the diagram is assigned the key. If one of the merchant accounts assigns a meta key to all of the transacting MIDs, only the transacting MIDs belonging to that merchant account are assigned the key. The portfolio or merchant account user can also choose specific transacting MIDs to assign the meta key to. #### Figure: Portfolio Hierarchy Example ![](/content/dam/new-documentation/documentation/en-us/topics/platform/bam/partner/images/portfolio-two-merchant-account-600x300.svg/jcr:content/renditions/original)