Security preferences

Security preferences provide 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). (The default is Elliptic Curve.)

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

How security preferences work

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) Optional (O) Conditional (C)
   securityPreferences	Object	Parent object that holds information about the security preferences.	R - You must provide this to use security preferences.
   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 receive notifications using tokens. Valid values are: none client_secret_post 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.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.authorizationDetails.clientCredentials	Object	Child object that holds client credential details.	C - You must provide this when tokenEndpointAuthorizationType = client_secret_post.
   securityPreferences.authorizationDetails.clientCredentials.clientSecret	String	A confidential string known only to the application and the authorization server.	O
   securityPreferences.authorizationDetails.clientCredentials.clientId	String	A public identifier for the application for authenticating the client.	O
   securityPreferences.authorizationDetails.clientCredentials.contentType	String	If your IDA server expects a value other than application/x-www-form-urlencoded, provide it here.	O
   securityPreferences.authorizationDetails.clientCredentials.clientCredentialRequestBody		Define parameters like grant type, scope, etc, to include in the request body.	O
   securityPreferences.authorizationDetails.jwtDetails		Child object that holds JSON Web Token (JWT) details.	C - you must provide this when tokenEndpointAuthorizationType = private_key_jwt.
   securityPreferences.authorizationDetails.jwtDetails.clientSecret	String	A confidential string known only to the application and the authorization server.	O
   securityPreferences.authorizationDetails.jwtDetails.jwtHeaderFields	String,String	Hash map object with key-value pairs that will be used as the header part of a JWT token.	O
   securityPreferences.authorizationDetails.jwtDetails.jwtRequestBody	String,String	Hash map object with key-value pairs that will be used as the body part of a JWT token.	O
   securityPreferences.authorizationDetails.jwtDetails.jwtRequestParameters	String,String	The JWT request parameters and values you expect to receive as part of authenticating into your servers for webhook delivery.	O
   securityPreferences.headerFields	Object	Hash map object with key-value pairs that are passed to the request header while connecting to the merchant server. These are additional headers that are sent on all auth and webhooks.	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 verifies the webhook subscription, processes the 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, the following happens:

   Webhook authorization type scenarios

   Scenario	What happens
   If webhookAuthorizationType = basic	The values in headerFields are added to the header of the webhook notification.
   If webhookAuthorizationType = token and tokenEndpointAuthorizationType = client_secret_post	The token is retrieved from the tokenEndpoint using the clientCredentials.clientId and clientCredentials.clientSecret, and attached to the webhook notification.
   If webhookAuthorizationType = token and tokenEndpointAuthorizationType = private_key_jwt	The token is retrieved from the tokenEndpoint, encrypted with the private JWT key (jwtHeaderFields, jwtRequestBody, jwtRequestParameters), and attached to the webhook notification. (decrypt it using the public key from GET /public-keys)
   If webhookAuthorizationType = token and tokenEndpointAuthorizationType = none	The token is retrieved from the tokenEndpoint and attached to the webhook notification.
   If mTLSEnabled = true	A mutual handshake for network security is done by using the certificates before sending the webhook notification. (You must share your certificate during onboarding)

4. After all the security preferences are added, the notification is signed using the signingAlgorithm you chose.
   • You can verify the webhook’s origin by decrypting the signature header value with the public key from GET /public-keys.
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 notification events along with the security preference for webhookAuthorizationType = token and tokenEndpointAuthorizationType = private_key_jwt.

Response:

Related

Subscribe to notifications
Retrieve notifications