Webhooks Overview

Webhooks are a means of allowing web based applications to communicate with one another. As certain events or actions occur within the Solaris API and/or wider Solaris system, the Solaris API can send corresponding notifications to your system. Such events might include a consumer's details being updated, a replacement card being issued or the completion of an automated process.

Webhook configuration and retry policy

Webhooks are sent from the API to pre-configured URLs on your system. You can subscribe to each notification type as required, and specify the URL that each type should be sent to:

• In the sandbox environment, you can configure these URLs in the Simulator Portal for testing and validation.
• In the production environment, webhooks are configured by the Solaris production team.

It is expected that a 200 OK response will be returned by your system to indicate successful receipt of the webhook. If such a response is not received, a further three retry attempts will be made at five minute intervals. If all four attempts fail, no further retries will be attempted.

Notification payloads

Along with the event specific payload, each notification will contain:

• A NotificationType field indicating the type of the notification being sent.
• A SecurityHash field, which contains the SHA256 security hash value of the payload body.

• Irrespective of their underlying data type, most values are sent as strings. The "Type" column in the notification's respective parameter listing denotes how each value should be treated/parsed.
• Boolean values are sent as strings, either as "True" , "False" or "1" , "0" not as JSON booleans ( true , false ).
• Status values commonly contain a leading zero, and are sent as strings: e.g. "07".
• DateTime values are sent in yyyyMMddHHmmss format (unless otherwise noted) with a timezone of UTC + 00:00.

{
  "NotificationType": "074",
  "CardActionCode": "09",
  "CardHolderId": "453158",
  "AccountNumber": "04261043 - 623053",
  "CardId": "322014",
  "CardNumber": "47451001",
  "RenewedCardId": "322015",
  "RenewedCardNumber": "47457696",
  "IsRenewedCardIssuedPhysically": "True",
  "SecurityHash": "9b52c53c7ca0ae3e0d40eaeddf61f5f8270de55c0cb53322ee89582444a468a2"
}

As shown in the example Card action notification payload above:

• Integer values (for example CardHolderId , CardId ) are sent as strings.
• The boolean value IsRenewedCardIssuedPhysically is sent as "True".
• The status value CardActionCode is sent as a string and contains a leading zero: "09".

Notification security hash

Each notification payload includes a SecurityHash field, which contains the SHA256 hash value of the payload body. This allows you to verify the notification has been sent by Solaris and the content is as expected. This value is computed by concatenating all values present in the payload (excluding the SecurityHash value itself) along with your webhook security key. The hash sequence for each notification is detailed on its respective page, with all values concatenated using the "&" (ampersand) character.

Payload special character transformations

Please note that when Solaris calculates the SecurityHash value from the notification payload, certain special characters in the payload are transformed, as below. To successfully and consistently calculate and validate these hash values for the notifications you receive, the same transformations must be performed on the payload content as part of your validation logic.

* When processing the 3DS SCA Notification, the "@" character in the Email parameter value should remain as is, and not be transformed.

Calculating and validating a notification security hash

In the following example, a partner whose webhook security key is "abcdefghijklmnop" has received a user status change notification with the following payload:

{
   "NotificationType" : "054",
   "CardHolderID" : "11",
   "OldUserStatus" : "01",
   "NewUserStatus" : "05",
   "StatusChangeDate" : "20180927213756",
   "SecurityHash" : "52441eba64461dc1866547bd7402fdad720216e49c3447d4e66eb59a09420cd0"
}

The hash sequence for the notification type is as follows:

<NotificationType>&<CardHolderId>&<OldUserStatus>&<NewUserStatus>&<StatusChangeDate>&<webhook-security-key>

By extracting the respective values, the following input for the hash function is produced:

054&11&01&05&20180927213756&abcdefghijklmnop

Hashing this value using SHA256 produces the following output:

52441eba64461dc1866547bd7402fdad720216e49c3447d4e66eb59a09420cd0

This output matches the value found in the SecurityHash field of the notification, verifying the payload.

Full list of notifications