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

Notification subscription

Certain workflows and reconciliation events may require you to subscribe to a given notification type.

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

All notification payloads are sent in JSON format, however due to reasons of legacy compatibility there are certain deviations from this standard formatting. When integrating a notification it is advised to familiarize yourself with both the respective payload parameters and example provided to mitigate any unexpected or non-standard behavior:

  • 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".
Copy
Copied
{
  "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

webhook security Key

You can find your Webhook security key in the API configuration file sent to you during onboarding.

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.

Input character(s) Transformed to
"\\" "\\\\"
"\" "\\\"
"\r\n" "\\r\\n"
"\r" "\\r"
"\n" "\\n"
"\t" "\\t"
"\b" "\\b"
"\f" "\\f"
"\0" " "
"\\u0000" " "
"&" "and"
"&" "and"
"N'" " "
"/" " "
"@" " "

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:

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

The hash sequence for the notification type is as follows:

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

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

Copy
Copied
054&11&01&05&20180927213756&abcdefghijklmnop

Hashing this value using SHA256 produces the following output:

Copy
Copied
52441eba64461dc1866547bd7402fdad720216e49c3447d4e66eb59a09420cd0

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

Full list of notifications

Notification type Codes

All notifications aside from the Token activation notification and Token OTP notification have three-digit codes.

Notification name Notification type code
Account Balance Change notification 060
Account Status Change notification 022
Authorization notification 052
Bank file notification 050
Card Action Notification 074
Card Shipment notification 067
Card Status change notification 021
Cross border payment regulation 2 notification 071
Direct Debit rejection notification 053
Fraud check notification 048
KYC Check notification 046
Pending authorization auto release notification 073
Token activation notification 68
Token OTP notification 55
Transaction notification 051
Transaction with available balance notification 056
User contact update notification 062
User login block/unblock notification 061
User status change notification 054
3DS SCA notification 059
Solaris is the brand name for the regulated entities Contis Financial Services Ltd and UAB „Finansinės paslaugos „Contis“, which are part of the Solaris Group.