Webhooks Implementation Guide

Production:

On the left navigation panel, choose

Payment Configuration > Key Management

.

Click

+ Generate key

on the Key Management page.

Under REST APIs, choose REST – Shared Secret
and then click Generate key
.

The REST API Shared Secret Key page appears.

Click Download key

.

The .pem
file downloads to your desktop.

To create or submit another key, click Generate another key
. To view all of your created keys, go to 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

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 might have already completed this requirement if your system is currently REST compliant.

Follow these steps to create a P12 certificate file or submit your own certificate signing request (CSR):

Log in to the Business Center:

Test:

Production:

On the left navigation panel, choose

Payment Configuration > Key Management

.

Click

+ Generate key

on the Key Management page.

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 Creating and Using Security Keys
.

Choose from these two options:

If you are a creating a new P12 Certificate, click

Download key

.

If you are submitting your own certificate, enter your public PEM-formatted certificate in the text box, then click

Download key

.

Create a password for the certificate by entering one into the

New Password

and

Confirm Password

fields. Click

Generate key

.

The .p12
file downloads to your desktop.

If prompted by your system, approve the location to which the key downloads.

To create or submit another key, click Generate another key
. To view all of your created keys, go to the Key Management page.

IMPORTANT

Securely store the .p12
file and password in your system.

Create a Digital Signature Key

Use the information in this section to create a digital signature key
. The Digital Signature Key request uses Visa's key management service to store your credentials. The Webhooks platform retrieves your credentials from key management to digitally authenticate your notifications.

You must create a digital signature key to enable Cybersource to send notifications to your servers. Replace the digital signature key every year. When you generate a new digital signature key, it overrides the old key and new transactions must use the new key.

Notifications that use message-level encryption must also the 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. For more information, see Validating a Notification with the Digital Signature Key.

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

clientRequestAction: Set the value to
CREATE
.
keyInformation.expiryDuration: Set to a number of days. We recommend
365
.
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

Digital Signature Key Request

{
  "clientRequestAction": "CREATE",
  "keyInformation": {
    "provider": "nrtd",
    "tenant": "merchantName",
    "keyType": "sharedSecret",
    "organizationId": "merchantName"
  }
}

Digital Signature Key Response

{
"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

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
.

Image and link to the interactive code example for creating a digital signature key. — Creating a Digital Signature Key

Validating a Notification with the Digital Signature Key

You can use the digital signature key to verify that the webhook notifications 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 key. You can configure your system to compare the notification's digital signature to the digital signature you created. If the digital signatures match, the notification is validated.

Complete these tasks to validate the webhook notifications that you receive:

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.

Extract the digital signature from the digital signature key that you created.

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

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.

Validating a Notification

Follow these steps to validate the integrity of your webhook notifications.

Separate the signature parameters with a semicolon (;) and extract the

t

,

keyId

, and

sig

values.

Use the

keyId

value to fetch the digital signature key.

Generate the payload by concatenating the timestamp and the payload from the body of the notification, using a period (.) to join them.

Use the SHA-256 algorithm to encrypt the generated payload from Step 3 using the key from Step 2.

Verify that the encrypted value matches the value in

sig

parameter.

Example: Validating a Notification

This example shows a system script that validates webhook notifications by comparing the merchant's digital signature with the webhook notification's signature. Use this example as a reference for how to 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;
    }
}

(Optional) Provide Your OAuth Credentials

If your system uses the OAuth
or OAuth with JWT
security policy, you must provide your OAuth credentials to Cybersource. The OAuth credentials request uses Visa's key management service to store your credentials. When Cybersource sends you webhook notifications in the future, Cybersource will use your OAuth credentials to access your server and deliver the notification message.

For more information about using OAuth, see OAuth 2.0 Partner Implementation Guide
.

IMPORTANT

If you are using only 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 that 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 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

Headers

Each API request should use headers that provide your client credentials, which are the username and password of your webhooks server. Here is an example:

curl --location 'Client's OAauth URL' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode ‘client_id=webhooks-server-username' \
--data-urlencode ‘client_secret=webhooks-server-password'

Required Fields for Providing Your OAuth Credentials

clientRequestAction: Set to
STORE
.
keyInformation.clientKeyId: Set to the webhook server's username.
keyInformation.expiryDuration: Set to
365
.
keyInformation.key: Set to the webhooks server'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

{
  "clientRequestAction": "STORE",
  "keyInformation": {
    "provider": "merchantName",
    "tenant": "nrtd",
    "keyType": "oAuthClientCredentials",
    "organizationId": "merchantName",
    "clientKeyId": "Webhook server's username",
    "key": "Webhook server's secret key",
    "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

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
.

Image and link to the interactive code example for providing your
OAuth credentials. — Providing Your OAuth Credentials

Retrieve a List of Products and Events

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 field 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 might 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.

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

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

Click this image to access the interactive code example for retrieving the product and event types enabled for your organization.

Image and link to the interactive code example for retrieving the
product and event types enabled for your organization. — Retrieve Product and Event Types

Message-Level Encryption

Message-level encryption (MLE) encrypts the payload of a message to prevent tampering. Payment and Unified Checkout events require message-level encryption. This section explains how to create the key that is necessary to decrypt encrypted payloads. To see which events require message-level encryption, see Supported Products and Event Types.

The webhook notification service requires X.509 certificates instead of raw public keys for MLE. The service uses:

Symmetric Encryption
: AES-GCM with 256-bit keys

Asymmetric Encryption
: RSA-OAEP with 2048-bit keys

Format
: JSON Web Encryption

Separate key pairs for request and response transactions

Prerequisite

OpenSSL must be installed on your system.

You must have access to terminal/command line.

You must appropriate permissions to create the asymmetric key in the Cybersource system.

Preparing Your Workspace

Open a terminal and navigate to a secure location for storing your key pairs:

mkdir -p ~/Cybersource-keys
				cd ~/Cybersource-keys

Generate Certificate and Key Pair

Run the following command, but replace

RequestKey

with your request key and replace

YourOrg

with your account organization ID:

openssl req -x509 -newkey rsa:2048 -keyout request_private.pem
 -out request_certificate.pem -days 365 -nodes -subj 
"/CN=RequestKey/O=YourOrg/C=US" && cat request_certificate.pem
 | grep -v "BEGIN CERTIFICATE" | grep -v "END CERTIFICATE" | 
tr -d '\n' && echo

Result

A 2048-bit RSA key pair is generated.

A self-signed X.509 certificate valid for 365 days is created.

The private key in

request_private.pem

is stored.

The certificate in

request_certificate.pem

is stored.

The certificate content is output as a single line, without headers.

Separate keys for each organization ID or account that uses message-level encryption are created.

Register the Certificate

Use the REST API to register and store your certificate. Each webhook subscription requires its own unique asymmetric certificate.

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 Registering Your Message-Level Encryption Keys

clientRequestAction: Set the value to
STORE
.
keyInformation.provider: Set the value to the name of the organization ID of the account.
keyInformation.tenant: Set the value to
nrtd
keyInformation.keyType: Set the value to
publickey
.
keyInformation.organizationId: Set the value to the name of the organization ID of the account.
keyInformation.pub: Set the value to the certificate that you generated in Generate Certificate and Key Pair.
keyInformation.expiryDuration: Set the value to
365
.

Example: Registering Your Certificate

{
						"clientRequestAction": "STORE",
						"keyInformation": {
						"provider": "<set this to your organization ID>",
						"tenant": "nrtd",
						"keyType": "publickey",
						"organizationId": "<set this to your organization ID>",
						"pub": "MIIDbDCCAlQCCQD4lcSlmasmCTANBgkqhkiG9w0B
						AQsFADB4MQswCQYDVQQGEwJVUzELMAkGA1UECAwCVFgxDzANBgNVBAcMBkF1c
						3RpbjENMAsGA1UECgwEVGVzdDEOMAwGA1UECwwFVGVzdDIxDjAMBgNVBAMMBV
						Rlc3QzMRwwGgYJKoZIhvcNAQkBFg10ZXN0QHRlc3QuY29tMB4XDTIxMDgwOTE
						0MTcxNFoXDTIyMDgwOTE0MTcxNFoweDELMAkGA1UEBhMCVVMxCzAJBgNVBAgM
						AlRYMQ8wDQYDVQQHDAZBdXN0aW4xDTALBgNVBAoMBFRlc3QxDjAMBgNVBAsMB
						VRlc3QyMQ4wDAYDVQQDDAVUZXN0MzEcMBoGCSqGSIb3DQEJARYNdGVzdEB0ZX
						N0LmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMcHQWZRETq
						im3XzUQlAiujFEvsHIi1uJZKj+1lvPH36Ucqo3ORcoh/MM/zxVdahjhSyyp7M
						HuKBWnzft6bFeDEul6qKWGPAAzaxG/2xZSV3FggA9SyAZEDUpJ6mblwqm/EY4
						KmZi1FrNBUHfW2wwaqDexHPRDesRG6aI7Wuu4GdQUUqoTa2+Nv7kVgEDmGcfI
						joWkGKHe+Yan95EITrq4jEFCE5Tg/vERnMvHfK2SovENZ13/pnwFYbeh1kfJS
						BzWW7yq8AyQAgAE9iqJXbJ/MAasir2vjUQ2+Hcl7WbkpoVjLqDt3rzV1T0Bsd
						4T9SC3wij9qjJSxa6vAgV4xn6bECAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAD
						uMrtYW1Sf0IsZ4ZD9ipjUrFuTxqh+0M5Jk8h0QqAXEHA/MawedlU3JmE3NB/U
						R82/XUwdmtObGnFANuUQQ+8WMFpcNo/Sq2kg7juneHZroRh72o73UUMtHWHzo
						8s0fXElNal8h3SaAAnjMblCiN+gM1RvWMvhGrMTXp2XAcdIezXf8/FOZLlzOF
						9QylbSk1U4ayWBag6MydkxgHjkPKdShZROEm0oz/O7J/gNp/r7J8F42Rw9MmJ
						h9qH3SFre13nQa8V7Kg+dJHZ/jpGtSlDHAxO0SSTrPXkwB+iBJ6hSkiL/J2Ep
						+lYHqVe3p5NXMOlTtJdbU4enHeLkD6PazKTw",
						"expiryDuration": "365"
						}
						}

{
						"submitTimeUtc": "2026-01-22T14:36:31Z",
						"status": "SUCCESS",
						"keyInformation": {
						"provider": "384259",
						"tenant": "nrtd",
						"organizationId": "384259",
						"keyId": "937dfa75-acff-4f5b-9aab-66a49455ae04",
						"pub": "MIIDbDCCAlQCCQD4lcSlmasmCTANBgkqhkiG9w0BAQsFADB4MQswCQYDVQQGEwJVUzELMAkGA1UECAwCVFgxDzANBgNVBAcMBkF1c3RpbjENMAsGA1UECgwEVGVzdDEOMAwGA1UECwwFVGVzdDIxDjAMBgNVBAMMBVRlc3QzMRwwGgYJKoZIhvcNAQkBFg10ZXN0QHRlc3QuY29tMB4XDTIxMDgwOTE0MTcxNFoXDTIyMDgwOTE0MTcxNFoweDELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAlRYMQ8wDQYDVQQHDAZBdXN0aW4xDTALBgNVBAoMBFRlc3QxDjAMBgNVBAsMBVRlc3QyMQ4wDAYDVQQDDAVUZXN0MzEcMBoGCSqGSIb3DQEJARYNdGVzdEB0ZXN0LmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMcHQWZRETqim3XzUQlAiujFEvsHIi1uJZKj+1lvPH36Ucqo3ORcoh/MM/zxVdahjhSyyp7MHuKBWnzft6bFeDEul6qKWGPAAzaxG/2xZSV3FggA9SyAZEDUpJ6mblwqm/EY4KmZi1FrNBUHfW2wwaqDexHPRDesRG6aI7Wuu4GdQUUqoTa2+Nv7kVgEDmGcfIjoWkGKHe+Yan95EITrq4jEFCE5Tg/vERnMvHfK2SovENZ13/pnwFYbeh1kfJSBzWW7yq8AyQAgAE9iqJXbJ/MAasir2vjUQ2+Hcl7WbkpoVjLqDt3rzV1T0Bsd4T9SC3wij9qjJSxa6vAgV4xn6bECAwEAATANBgkqhkiG9w0BAQsFAAOCAQEADuMrtYW1Sf0IsZ4ZD9ipjUrFuTxqh+0M5Jk8h0QqAXEHA/MawedlU3JmE3NB/UR82/XUwdmtObGnFANuUQQ+8WMFpcNo/Sq2kg7juneHZroRh72o73UUMtHWHzo8s0fXElNal8h3SaAAnjMblCiN+gM1RvWMvhGrMTXp2XAcdIezXf8/FOZLlzOF9QylbSk1U4ayWBag6MydkxgHjkPKdShZROEm0oz/O7J/gNp/r7J8F42Rw9MmJh9qH3SFre13nQa8V7Kg+dJHZ/jpGtSlDHAxO0SSTrPXkwB+iBJ6hSkiL/J2Ep+lYHqVe3p5NXMOlTtJdbU4enHeLkD6PazKTw",
						"keyType": "publickey",
						"status": "active",
						"expirationDate": "2022-08-09T14:17:14Z"
						}
						}

REST Interactive Example: Registering Your Certificate

Click this image to access the interactive code example for registering your certificate. The Live Console refers to this request as Message-Level Encryption
.

Security Best Practices

Here are some tips to ensure that your keys remain secure.

Store private keys in a secure location with restricted permissions.

Never commit private keys to version control.

Rotate certificates before expiration.

Use environment variables or secure vaults for production deployments.

Keep back-up copies of your private keys in a secure location.

Securing Your Private Key

Keep your request_private.pem
file secure. This private key is required to decrypt incoming webhook notifications. To modify the permissions so that only the file owner can read and write to the files, use this command:

chmod 600 request_private.pem

Troubleshooting

If you receive the Key invalid or validity too long
error, try generating a certificate with shorter validity:

# 90-day validity
openssl req -x509 -newkey rsa:2048 -keyout request_private.pem
 -out request_certificate.pem -days 90 -nodes -subj 
"/CN=RequestKey/O=YourOrg/C=US" && cat request_certificate.pem
 | grep -v "BEGIN CERTIFICATE" | grep -v "END CERTIFICATE" | 
tr -d '\n' && echo

Viewing Certificate Details

To verify your certificate details, use this command.

openssl x509 -in request_certificate.pem -text -noout

Create a Webhook Subscription

This section describes how to create webhook subscription using mutual trust. Mutual trust is the default security policy. For more information, see Set Up Your Security.

You can subscribe to multiple webhook products and event types in the same request.

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.

Retry Policy

If your webhook URL or health check URL are unresponsive when sent a notification, Cybersource resends the notification according to the subscription's retry policy
. By default, Cybersource sends you 3 notification attempts, beginning 1 minute after the initial failed attempt. Retry attempts occur in 1 minute intervals if your URL remains unresponsive. You can configure the default retry policy when you create or update a subscription. For more information about how to configure the retry policy, see Configure the Retry Policy.

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.

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

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.
products.productId: For a list of product IDs, see Supported Products and Event Types.
securityPolicy.securityType: Set to
KEY
.
webhookUrl

Optional Fields for Subscribing to Webhooks

deactivateflag: Required when the
healthCheckUrl
field is present.; Set to
true
to automatically activate the subscription.
healthCheckUrl: Set to the health check URL. Required to auto-activate the subscription. If you do not include this field, the created subscription is inactive. An inactive subscription does not send notifications. For more information, see Webhook Health Check URL and Automatic Revalidation.
notificationScope.scopeData: Set to the organization IDs that you want to have receive notifications when events occur in those organizations. Concatenate each organization ID with the comma character (
,
).
retryPolicy.deactivateFlag: For more information, see Configure the Retry Policy.
retryPolicy.firstRetry: For more information, see Configure the Retry Policy.
retryPolicy.interval: For more information, see Configure the Retry Policy.
retryPolicy.numberOfRetries: For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceCount: For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceWaitTime: For more information, see Configure the Retry Policy.

Example: Creating a Webhook Subscription

{
  "name": "My Custom Webhook",
  "description": "Sample Webhook from Developer Center",
  "organizationId": "<SET TO YOUR ORGANIZATION ID OR MERCHANT ID>",
  "products": [
    {
      "productId": "product1.name",
      "eventTypes": [
        "product.name.event.type"
        "product.name.event.type"
        "product.name.event.type"
      ]
    }
    {
      "productId": "product2.name",
      "eventTypes": [
        "product.name.event.type"
        "product.name.event.type"
        "product.name.event.type"
        "product.name.event.type"
        "product.name.event.type"
        "product.name.event.type"
      ]
    }
  ],
  "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient",
  "securityPolicy": {
    "securityType": "KEY"
  }
}

Response to a Successful Request

{
  "organizationId": "organizationId",
  "productId": "terminalManagement",
  "eventTypes": [
    "terminalManagement.assignment.update"
  ],
  "webhookId": "ddb9bced-c3e3-1b1d-e053-9c588e0a3c42",
  "name": "My Custom Webhook",
  "webhookUrl": "https://MyWebhookServer.com:443/simulateClient",
  "healthCheckUrl": "https://MyWebhookServer.com:443/simulateClientHealthCheck",
  "createdOn": "2022-04-28T15:39:56.928Z",
  "status": "ACTIVE",
  "description": "Sample Webhook from Developer Center",
  "retryPolicy": {
    "algorithm": "ARITHMETIC",
    "firstRetry": "1",
    "interval": "1",
    "numberOfRetries": "3",
    "deactivateFlag": "false",
    "repeatSequenceCount": '0",
    "repeatSequenceWaitTime": "0"
  },
  "securityPolicy": {
    "securityType": "KEY",
    "digitalSignatureEnabled": "yes"
  },
  "version": "3",
  "notificationScope": "SELF"
}

Response Codes

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

.

Notification Scope Response Indicators

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

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.

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

Click this image to access the interactive code example for creating a webhook subscription.

Image and link to the interactive code example for creating a webhook
subscription. — Create a Webhook Subscription

Create a Webhook Subscription Using OAuth

This section describes how to create a webhook subscription using the OAuth security policy, in addition to mutual trust. You can subscribe to multiple webhook products and event types in the same request. After creating a subscription, you receive a notification every time your subscribed events occur.

The OAuth
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.

Retry Policy

If your webhook URL or health check URL are unresponsive when sent a notification, Cybersource resends the notification according to the subscription's retry policy
. By default, Cybersource sends you 3 notification attempts, beginning 1 minute after the initial failed attempt. Retry attempts occur in 1 minute intervals if your URL remains unresponsive. You can configure the default retry policy when you create or update a subscription. For more information about how to configure the retry policy, see Configure the Retry Policy.

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.

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

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.
products.productId: For a list of product IDs, see Supported Products and Event Types.
securityPolicy.config.oAuthTokenExpiry
securityPolicy.config.oAuthTokenType: Set to
Bearer
.
securityPolicy.config.oAuthURL: This is the URL of your OAuth server.
securityPolicy.securityType: Set to
oAuth
.
webhookUrl

Optional Fields for Subscribing to Webhooks Using OAuth

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.
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.
retryPolicy.firstRetry: For more information, see Configure the Retry Policy.
retryPolicy.interval: For more information, see Configure the Retry Policy.
retryPolicy.numberOfRetries: For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceCount: For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceWaitTime: For more information, see Configure the Retry Policy.

Example: Creating a Webhook Subscription Using OAuth

{
  "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

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

.

Notification Scope Response Indicators

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

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.

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

Click this image to access the interactive code example for creating a webhook subscription using OAuth.

Image and link to the interactive code example for creating a
webhook subscription using OAuth. — Create a Webhook Subscription Using OAuth

Create a Webhook Subscription Using OAuth with JWT

This section describes how to create a webhook subscription using OAuth with a JSON Web Token (JWT), in addition to mutual trust. You can subscribe to multiple webhook products and event types in the same request. After creating a subscription, you receive a notification every time your subscribed events occur.

The OAuth with JWT
security policy is an authentication method in which your system sends a JSON Web Token. This method bypasses domain headers and minimizes the need for server-side authentication checks.

Health Check URL

Cybersource recommends that you include a health check URL in the subscription request. A health check URL ensures that you do not miss any notifications. For more information, see Webhook Health Check URL and Automatic Revalidation.

Retry Policy

If your webhook URL or health check URL are unresponsive when sent a notification, Cybersource resends the notification according to the subscription's retry policy
. By default, Cybersource sends you 3 notification attempts, beginning 1 minute after the initial failed attempt. Retry attempts occur in 1 minute intervals if your URL remains unresponsive. You can configure the default retry policy when you create or update a subscription. For more information about how to configure the retry policy, see Configure the Retry Policy.

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.

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

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.
products.productId: For a list of product IDs, see Supported Products and Event Types.
securityPolicy.config.additionalConfig.aud
securityPolicy.config.additionalConfig.client_id
securityPolicy.config.additionalConfig.keyId
securityPolicy.config.additionalConfig.scope
securityPolicy.config.oAuthTokenExpiry: Set to
365
.
securityPolicy.config.oAuthTokenType: Set to
Bearer
.
securityPolicy.config.oAuthUrl: This is the URL of your OAuth server.
securityPolicy.securityType: Set to
oAuth_JWT
.
webhookUrl

Optional Fields for Subscribing to Webhooks Using OAuth with JWT

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.
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.
retryPolicy.firstRetry: For more information, see Configure the Retry Policy.
retryPolicy.interval: For more information, see Configure the Retry Policy.
retryPolicy.numberOfRetries: For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceCount: For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceWaitTime: For more information, see Configure the Retry Policy.

Example: Creating a Webhook Subscription Using OAuth with JWT

{
  "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

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

.

Notification Scope Response Indicators

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

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.

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

Click this image to access the interactive code example for creating a webhook subscription using OAuth with JWT.

Image and link to the interactive code example for creating a
webhook subscription using OAuth with JWT. — Create a Webhook Subscription Using OAuth with JWT

Create a Sample Webhook Subscription

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 account or organization ID is enabled for TMS and that a TMS vault is set up. For assistance, contact Cybersource Customer Support.

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

. The following 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"
  }
}

Go to the Create an Instrument Identifier section in the API Reference.

Click the Configuration
tab.

In the Sample Request drop-down menu, choose

Create Instrument Identifier using a Card and Create Network Token

:

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

{
  "type": "enrollable card",
  "card": {
    "number": "411111111111XXXX",  // Replace the ‘X’s with 1
    "expirationMonth": "12",
    "expirationYear": "2031"
  }
}

IMPORTANT

A test PAN can have only 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
.

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.

Optional Set-Up Tasks

You can complete optional set-up tasks during or after creating a webhook subscription. These tasks are optional and are not required in order 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

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 five to ten 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.

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

If your webhook URL or health check URL are unresponsive, Cybersource resends the webhook notifications according to the subscription's retry policy
. All subscriptions have a default retry policy (see the default values in the field descriptions below). You can change the retry policy when you create a subscription or update the webhook subscription by modifying the retry field values described below.

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 values:; false
: Notifications are not
withheld when your webhook URL or health check URL are unresponsive. This value is the default.
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

This example shows how to format a retry policy in a request.

  "retryPolicy": {
    "firstRetry": "1",
    "interval": "1",
    "numberOfRetries": "3",
    "deactivateFlag": "false",
    "repeatSequenceCount": "0",
    "repeatSequenceWaitTime": "0"
  }

Webhook Notification Field Descriptions

Each webhook notification that you receive contains a message body with fields. This section describes the possible fields and values you can receive in a notification. The default version of the Webhooks API is version 3, and the information in this section describes version 3.

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.
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: Notification Payload

TMS Webhook Notification

Headers
POST /test HTTP/1.1Host: test.test.comContent-Length: 537 Content-Type: 
application/jsonv-c-event-type: product.event.typev-c-organization-id: 
orgidv-c-product-name: productv-c-request-type: NEWv-c-retry-count: 0
v-c-signature "t=timestamp;keyId=key-UUID;sig=calculatedDigitalSignature"
v-c-transaction-trace-id: "7ac2ad9f-6a89-d3e9-e053-34b8d30aaf40"
v-c-webhook-id: "e339e8b1-d540-4efd-e053-8d588e0a2de5"

Body Payload
{
    "eventType": "tms.networktoken.provisioned",
    "webhookId": "e339e8b1-d540-4efd-e053-8d588e0a2de5",
    "productId": "tokenManagement",
    "organizationId": "sampleSubscriptionHolder",
    "eventDate": "2022-07-20T11:38:45",
    "transactionTraceId": "7ac2ad9f-6a89-d3e9-e053-34b8d30aaf40",
    "retryNumber": 0,
    "payload": {
      "data": {
        "_links": {
          "paymentInstruments": [
             {
               "href": "/tms/v1/paymentinstruments/...................."
             }
           ],
           "instrumentIdentifiers": [
             {
               "href": "/tms/v1/instrumentidentifiers/...................."
                 }
            ]
          },
            "id": "...................",
            "type": "tokenizedCardEnrollments",
            "version": "1.0"
        },
        "organizationId": "sampleSelfOrChildOrg"
    },
    "requestType": "NEW"
}

Manage Webhook Subscriptions Requests

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

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

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

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

.

REST Interactive Example: Retrieve the Details of a Webhook Subscription

Click this image to access the interactive code example for retrieving the details of a webhook subscription.

Image and link to the interactive code example for retrieving the
details of a webhook subscription. — Retrieve the Details of a Webhook Subscription

Retrieve All of an Organization's Subscriptions

This section describes how to retrieve a list of the webhook subscriptions to which an organization subscribes. 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

eventType: Set to an event type. For a list of event types, see Supported Products and Event Types.
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.

Optional Query Parameters for Retrieving All of an Organization's Subscriptions

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.
productId: Set to a product ID. For a list of product IDs, see Supported Products and Event Types.

Example: Retrieving All of an Organization's Subscriptions

GET https://apitest.cybersource.com/notification-subscriptions/v2/webhooks?organizationId=organization123&productId=tokenManagement&eventType=tms.networktoken.provisioned

Response Codes

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

.

REST Interactive Example: Retrieving all of an Organization's Subscriptions

Click this image to access the interactive code example for retrieving an organization's subscription using the product and event.

Image and link to the interactive code example for retrieving an
organization's subscription using the product and event. — Retrieve an Organization's Subscriptions Using the Product and Event

Update a Webhook Subscription

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

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 in order 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.
name
organizationId: Set to your organization ID or merchant ID.
products.eventTypes: For a list of event types, see Supported Products and Event Types.
products.productId: For a list of product IDs, see Supported Products and Event Types.
retryPolicy.deactivateFlag: For more information, see Configure the Retry Policy.
retryPolicy.firstRetry: For more information, see Configure the Retry Policy.
retryPolicy.interval: For more information, see Configure the Retry Policy.
retryPolicy.numberOfRetries: For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceCount: For more information, see Configure the Retry Policy.
retryPolicy.repeatSequenceWaitTime: For more information, see Configure the Retry Policy.
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

{
  "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

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

.

REST Interactive Example: Updating a Webhook Subscription

Click this image to access the interactive code example for updating a webhook subscription.

Image and link to the interactive code example for updating a
webhook subscription. — Updating a Webhook Subscription

Delete a Webhook Subscription

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

DELETE https://apitest.cybersource.com/notification-subscriptions/v2/webhooks/b555a545-58a9-47c7-aef9-10a8e17f201a

{
    "status": "successfully deleted"
}

Response Codes

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

.

REST Interactive Example: Deleting a Webhook Subscription

Click this image to access the interactive code example for deleting a webhook subscription.

Image and link to the interactive code example for deleting a
webhook subscription. — Deleting a Webhook Subscription

Verify a Webhook Subscription's Configuration

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.

Endpoints

Send a POST request to one of these endpoints. The {webhookId}
is the webhook subscription ID.

IMPORTANT

This endpoint uses the

/v1/

path segment.

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

Request

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

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

.

REST Interactive Example: Verifying a Webhook Subscription's Configuration

Click this image to access the interactive code example for testing a webhook subscription configuration.

Image and link to the interactive code example for testing a
webhook subscription configuration. — Testing a Webhook Subscription Configuration

Activate a Webhook Subscription

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

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

Request

PUT https://apitest.cybersource.com/notification-subscriptions/v2/webhooks/ddb9bced-c3e3-1b1d-e053-9c588e0a3c42

Response to a Successful Request

{
  "status": "ACTIVE"
}

Response Codes

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

.

REST Interactive Example: Activating a Webhook Subscription

Click this image to access the interactive code example for activating a webhook subscription.

Image and link to the interactive code example for activating a
webhook subscription. — Activating a Webhook Subscription

Deactivate a Webhook Subscription

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

Request

PUT https://apitest.cybersource.com/notification-subscriptions/v2/webhooks/ddb9bced-c3e3-1b1d-e053-9c588e0a3c42

Response to a Successful Request

{
  "status": "INACTIVE"
}

Response Codes

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

.

REST Interactive Example: Deactivating a Webhook Subscription

Click this image to access the interactive code example for deactivating a webhook subscription.

Image and link to the interactive code example for deactivating a
webhook subscription. — Deactivating a Webhook Subscription

Troubleshooting Webhook Subscriptions

If you created a webhook subscription but are not receiving notifications, consider the following:

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. If the organization is not in the notification scope, you must update the webhook subscription. For more information, see Update a Webhook Subscription.

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. 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.

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"

Step 2A: Create or Submit a P12 Certificate

Follow these steps to create a P12 certificate file or submit your own certificate signing request (CSR):

Log in to the Business Center:

Test:

Production:

https://developer.cybersource.com/api-reference-assets/index.html#payments_payments_static-home-section

On the left navigation panel, choose

Payment Configuration > Key Management

.

Click

+ Generate key

on the Key Management page.

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 Creating and Using Security Keys
.

Choose from these two options:

If you are a creating a new P12 Certificate, click

Download key

.

If you are submitting your own certificate, enter your public PEM-formatted certificate in the text box, then click

Download key

.

Create a password for the certificate by entering one into the

New Password

and

Confirm Password

fields. Click

Generate key

.

The .p12
file downloads to your desktop.

If prompted by your system, approve the location to which the key downloads.

To create or submit another key, click Generate another key
. To view all of your created keys, go to the Key Management page.

IMPORTANT

Securely store the .p12
file and password in your system. These credentials are required in order to implement certain products, and you must be able to access them.

Step 2B: Test Your Shared Secret Key Pair

After creating your key certificate, you must verify that your key can successfully process API requests. Follow these steps to validate your key certificate in the Developer Center and the Business Center.

Go to the Developer Center's API Reference page:

On the left navigation panel, click API Endpoints & Authentication
.

Under Authentication and Sandbox Credentials, go to the Authentication Type drop-down menu and choose HTTP Signature
.

Enter your organization ID in the Organization ID
field.

Enter your key, also known as your private key, in the Key
field.

Enter your secret key, also known as your public key, in the Shared Secret Key
field.

Click Update Credentials
.

Go to the Developer Center's API Reference and navigate to Payments >
POST
Process a Payment
.

Click Send
.

A message confirms that your request was successful with the status code 201.

Log in to the Business Center:

On the left navigation panel, choose

Transaction Management > Transactions
.

Under Search Results, verify that the request ID from the test authorization response is listed in the Request ID column.

If the test authorization was successful, a success message is present in the corresponding Applications column.

Create a REST API Key

REST API security keys are used to enable secure communication between the merchant and Cybersource when using REST APIs.

The REST API supports two types of security keys:

P12 certificate
for using JSON Web Token authentication. See Step 2A: Create or Submit a P12 Certificate.

Shared secret key
for using HTTP signature authentication. See Step 2A: Creating a Shared Secret Key Pair.

REST API keys expire after 3 years.

Security keys can be used to make any request, including payments. Treat your security keys as you would any secure password.

You must use separate keys for the test and production environments.

When you sign up for a Sandbox account, your confirmation email contains a key and shared secret key for HTTP Signature authentication.

For more information about the REST API, see the REST Getting Started Guide.

Step 2A: Creating a Shared Secret Key Pair

Follow these steps to create a shared secret key pair:

Log in to the Business Center:

Test:

Production: