Skip to main content
optimization protection

Security preferences

Security preferences provides you the option to add an additional layer of security by allowing you to add Open Authentication (OAuth) and Secure Socket Layer (SSL) certificates authentication on webhook notifications. You can authenticate against the callback URL using the security preference details you provide at the time of subscription.

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.
    Required fields for OAuth and SSL authentication on webhook notifications
    Field name Data type Description Required (R) or Optional (O)
    securityPreferences Object Parent object that holds information of the security preferences. R
    securityPreferences.oAuthNotificationEnabled Boolean Indicates that you are set up to receive notification messages supported by Open Authorization standard such as webhook notifications. O
    securityPreferences.sslAuthNotificationEnabled Boolean Indicates that you are set up to receive notification messages supported by Secure Socket Layer certificates authenticatication standard. O (if set to true, you must have JPMC's certificate whitelisted to do two-way SSL authentication)
    securityPreferences.headerFields Object Hashmap object with key value pairs that need to pass into request header while connecting to merchant server. Merchant put validations based on those headers and their values at their side. O
    securityPreferences.oAuthDetails Object Child object for information on OAuth details to apply when sending webhook notifications. O (Required if opted for OAuth authentication)
    securityPreferences.oAuthDetails.oAuthClientSecret String A confidential string known only to the application and the authorization server. O
    securityPreferences.oAuthDetails.oAuthClientId String Public identifier for the application using OAuth for authenticating the client. O
    securityPreferences.oAuthDetails.tokenURL 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
  2. Notifications API backend processes the subscription request and stores the authentication details you sent.
  3. When the notification event you subscribed to occurs, the Notifications API uses the authentication credentials you provide (tokenURL) to retrieve the token.
  4. Then it adds the certificate and token to the webhook notification and sends it to the callbackUrl.
  5. You authenticate against the callback URL and validate its authenticity to ensure it came from J.P. Morgan.

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 OAuth and SSL authentication.

Json
{
    "notifications": {
        "tokenLifecycleNotification": [
            "All"
        ],
        "recurringProgramNotification": [
            "PlanUpdated",
            "ConsumerCommunicationUpdated",
            "PaymentApplied",
            "PaymentNotApplied",
            "ProgramUpdated"
        ]
    },
    "securityPreferences": {
        "oAuthNotificationEnabled": true,
        "sslAuthNotificationEnabled": true,
        "headerFields": {
            "key1": "value1",
            "key2": "value2"
        },
        "oAuthDetails": {
            "oAuthClientSecret": "ab3sgdLdSX8szxD",
            "oAuthClientId": "sE4sasddaKJ4sfdfdEasQfsdAeeWaSa",
            "tokenURL": "https://api-uat.merchant.com/oauth/client_credential/accesstoken"
        }
    },
    "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"
    }
}