Subscribing to Webhooks Using OAuth

This section describes the tasks that you must accomplish in order to subscribe to webhooks using OAuth.

Webhooks Subscription Workflow Using OAuth

Follow these steps to set up your webhooks subscription using OAuth:
  1. Set up your server security to receive webhooks notifications.
  2. Generate API security keys for authenticating API requests. You must generate separate keys for the testing and production environments.
  5. Request a product list.
  6. Subscribe to webhooks event notifications.

Setting Up Server Security

Take these actions to secure your server to receive webhooks notifications.

Allowlist

Allow these IP addresses. Our test and production servers can use either address:
  • 198.241.206.21
  • 198.241.207.21

Trusting the Root Certificate

Download the certificate, "Visa Corporate Root CA G2" from enroll.visacajava.io.PrintWriter@6b94d5fb .com, and add it to your Java keystore.

Create a Shared Secret Key Pair

Follow these steps to create a shared secret key pair.
  1. Log in to the
    Business Center
    :
  2. On the left navigation panel, navigate to
    Payment Configuration > Key Management
    .
  3. Click
    + Generate key
    .
  4. Under REST APIs, select
    REST – Shared Secret
    and then click
    Generate key
    .
    The REST API Shared Secret Key page appears.
  5. Click
    Download key
    .
    The .pem file is downloaded to your desktop.
When you generate one or more keys, you can view the keys on the Key Management page.

Requesting a Digital Signature Key

A digital signature key is required before you can subscribe to webhooks notifications. The API request to generate the digital signature key is documented in this section. We use the digital signature key to add a unique signature to each notification. You can use the digital signature key to validate the integrity of webhooks notifications and prevent replay attacks. To verify the integrity of a notification payload using the digital signature key, see Notification Validation.
To request the service, use the endpoint specified below. After you send the request, check the response message to verify that the request was successful. A 200-level response code indicates success.
For information about response codes, see
Transaction Response Codes
.

Endpoint

  • Test:
    POST
    apitest.cybersource.com
    /kms/egress/v2/keys-sym
  • Production:
    POST
    api.cybersource.com
    /kms/egress/v2/keys-sym
  • Production
    in India:
    POST api.in.cybersource.com/kms/egress/v2/keys-sym

Sending OAuth Credentials

If you use OAuth, you must send credentials for your OAuth server so that notifications are authenticated.
To request the service, use the endpoint specified below. After you send the request, check the response message to verify that the request was successful. A 200-level response code indicates success.
For information about response codes, see
Transaction Response Codes
.

Endpoint

  • Test:
    POST
    apitest.cybersource.com
    /kms/egress/v2/keys-sym
  • Production:
    POST
    api.cybersource.com
    /kms/egress/v2/keys-sym
  • Production
    in India:
    POST api.in.cybersource.com/kms/egress/v2/keys-sym

Products and Events

Discover the products and events to which you can subscribe by sending an API request to retrieve the list of all of the products and events that are enabled and configured for your account. You can subscribe to webhooks only for products and services that are enabled and configured for your account. The API response includes an array of products with all of the event types included in the
eventTypes
fields.

Subscribing to Webhooks Using OAuth

This section describes the API request used to subscribe to a webhook using OAuth. You can only subscribe to one webhook per API request.
To request the service, use the endpoint specified below. After you send the request, check the response message to verify that the request was successful. A 200-level response code indicates success.
For information about response codes, see
Transaction Response Codes
.

Endpoint

  • Test:
    POST
    apitest.cybersource.com
    /notification-subscriptions/v1/webhooks
  • Production:
    POST
    api.cybersource.com
    /notification-subscriptions/v1/webhooks
  • Production in India:
    POST api.in.cybersource.com/notification-subscriptions/v1/webhooks

Notification Format

Each event notification contains headers and the body of the message.

Notification Headers

These headers are sent with every notification. Some headers are duplicates of the fields in the body.
V-C-signature
Contains the digital signature, which can be used for validating the security of the notification.
V-C-event-type
Type of event that generated the notification.
V-C-organization-id
Identifier of the organization that subscribed to the notification.
V-C-product-name
Name of the product for which the event occurred.
V-C-request-type
New or retry.
V-C-retry-count
Number of times the notification was resent.
V-C-transaction-trace-id
Identifier of the notification attempt. For example, every time a notification is retried, each attempt has a different transaction trace ID and the same notification ID.
v-c-webhook-id
Identifier of the webhook subscription that generated the notification.

Notification Body

The body of the message contains fields associated with the notification itself and the payload of the event that generated the notification.
webhookId
Identifier of the webhook subscription that generated the notification.
transactionTraceId
Identifier of the notification attempt. For example, every time a notification is retried, each attempt has a different transaction trace ID and the same webhook ID.
productId
Identifier of the product that generated the event.
organizationId
Identifier of the organization that subscribed to the notification.
eventType
The type of event that generated the notification.
eventDate
Timestamp of the event.
payload
The data generated by the event.
requestType
New or retry.