Skip to main content

Security preferences

Security preferences provides you the option to add additional layers of security for your webhook notifications by:

  • Adding webhook authorization details
  • Changing the Digital Signing Algorithm to Rivest-Shamir-Adelman (RSA). (default is Elliptic Curve)

This allows you to have Open Authorization (OAuth) protected callback URLs where webhook notifications are delivered using the authorization details you provide in securityPreferences.

How it works

  1. You subscribe to the notification events of your choice by performing a POST call to the /subscriptions endpoint along with the following authentication fields.
    Fields for webhook and token authorization, and digital signing algorithm on webhook notifications
    Field name Data type Description Required (R) or Optional (O) or Conditional (C)
    securityPreferences Object Parent object that holds information of the security preferences. R - You must provide this to use this feature.
    securityPreferences.webhookAuthorizationType String

    Authorization setup that is needed to receive notifications supported by Open Authorization standard such as webhook notifications. Valid values are:

    • none - No webhook authorization.
    • basic - Basic authorization using the Authorization key value provided in headerFields.
    • token - OAuth using the values provided in authorizationDetails.
    		 O
    securityPreferences.tokenEndpointAuthorizationType String

    Authorization setup that is needed to recieve notifications using tokens. Valid values are:

    • none
    • client_secret_post
    • client_secret_jwt
    • private_key_jwt
    		 C - You must provide this when webhookAuthorizationType = token.
    securityPreferences.mTLSEnabled Boolean

    Indicates that mutual Transport Layer Security for handshake certificate validation is enabled or disabled.

    If set to true, you must share your certificate during onboarding.

    		 O
    securityPreferences.authorizationDetails Object Child object that holds additional authorization details to apply when sending webhook notifications. C - You must provide this when webhookAuthorizationType = token.
    securityPreferences.authorizationDetails.clientSecret String A confidential string known only to the application and the authorization server. O
    securityPreferences.authorizationDetails.clientId String A public identifier for the application for authenticating the client. O
    securityPreferences.authorizationDetails.tokenEndpoint String A reference to a web resource on the internet that specifies the location and mechanism for the identity provider to fetch the token. O
    securityPreferences.headerFields Object Hashmap object with key value pairs that are passed to the request header while connecting to the merchant server.  C - You must provide this when webhookAuthorizationType = basic
    securityPreferences.signingAlgorithm String

    Enumerates the Digital Signing Algorithm preferred by the client. This is used to sign payloads and for identity verification. 

    • For Rivest-Shamir-Adelman (RSA) key length will be 3072 
    • For Elliptic Curve (EC) key length will be 256.

    If no value is provided for this field, the default value is EC.

    		 O
  2. Notifications API backend processes the subscription request and stores the header fields and authorization details you sent, based on the authorization type you chose.
  3. When the notification event you subscribed to occurs:
    • If webhookAuthorizationType = basic, the values in headerFields is added to the header of the webhook notification.
    • If webhookAuthorizationType = token, the token is retrieved from the tokenEndpoint using the clientId and clientSecret, and attached to the webhook notification.
    • If mTLSEnabled = true, mutual handshake for network security is done by using the certificates before sending the webhook notification.
  4. Once all the security perferences are added, the notification is encrypted using the signingAlgorithm you chose.
  5. The encrypted webhook notification is sent to the OAuth protected callbackUrl using the authorization details you provided.

The following example shows how to send the security preference details when you subscribe to a notification.

HTTP method: POST

Endpoint: /subscriptions

Scenario: Subscribing to notifications events and providing the security preference details for token webhook authorization with RSA signing algorithm.

Json
{
    "notifications": {
        "tokenLifecycleNotification": [
            "All"
        ],
        "recurringProgramNotification": [
            "PlanUpdated",
            "ConsumerCommunicationUpdated",
            "PaymentApplied",
            "PaymentNotApplied",
            "ProgramUpdated"
        ]
    },
    "securityPreferences": {
        "webhookAuthorizationType": "token",
        "tokenEndpointAuthorizationType": "private_key_jwt",
        "mTLSEnabled": true,
        "authorizationDetails": {
            "clientId": "3e28334a-1b7d-480a-a35d-12345",
            "tokenEndpoint": "https://api-idp-server.com/merchant/v1/getToken"
        },
        "headerFields": {
            "Authorization": "Basic Y1Q1M0pEaEdKNGdCNWpsWnRPQVN6eWowaEd6QQ==",
            "Api-Key": "12345678"
        },
        "signingAlgorithm": "RSA"
    },
    "subscriptionChannels": [
        "WEBHOOK"
    ],
    "callBackUrl": "https://merchant.notification.com"
}

Response:

Json
{
    "notifications": {
        "tokenLifecycleNotification": [
            "All"
        ],
        "recurringProgramNotification": [
            "PlanUpdated",
            "ConsumerCommunicationUpdated",
            "PaymentApplied",
            "PaymentNotApplied",
            "ProgramUpdated"
        ]
    },
    "subscriptionId": "f07e8898-2819-44eb-989f-e04607766c10",
    "subscriptionCreatedTimestamp": "2024-01-09T10:05:42.522Z",
    "subscriptionUpdatedTimestamp": "2024-01-09T10:05:42.522Z",
    "callbackURL": "https://merchant.notification.com",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "Request Accepted",
    "publicKey": {
        "publicKeyIdentifier": "213db467b83c4db2a69da08705eff25a",
        "publicKeyText": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvsoc/9/GmHzXSw7JBpGc7zJx5TYRJXmQxG2Dnx2BZ+ELQEliL6oCOUpAxx+TW61BmVdCabh+i43biOPicgXY/A==",
        "publicKeyExpirationDate": "2024-10-31T13:10:30.481Z"
    },
    "subscriptionChannels": [
        "WEBHOOK"
    ]
}