Webhook-Version 2 Migration

Overview

We have developed a Webhook-Version 2 that includes changes to the following aspects:

  • Update webhook verification to HMAC_SHA256.
  • Pass Company-Id and Mid header parameters only as GUIDs.
  • Updated the webhook structure to remove the timestamp from the webhook_body object.
  • Revised the webhook_id GUID to consistently default to lowercase.

A small migration effort is required from merchants who currently utilise Webhook-Version 1 and solely relates to the validation process for ensuring webhook integrity.

Validating the integrity of the webhook (Version 1)

To validate the integrity of the webhook you generate a new hash value and compare it to the returned hash value. If the values match then the data has not been altered and the integrity of the data has been verified.

Follow the below steps to calculate the hash value:

  1. Concatenate the parameters in this order: status. transaction_id. order_id. timestamp

executed1970f4e1-95da-4859-b275-e9ac83f05eb1your_unique_reference_11657183950

  1. SHA256 encrypt the resulting string.

4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007

  1. Append your app_key value to the hash value of a string.

4e9ce34004008830e672aa826efd5ddf56130ad127c279751135d48291b5f007app_key

  1. SHA256 the resulting string.

6a8310c7510493b87c0dc0fec7c4df4091eb021c040ee8b3dbf134f1c1ec6731

  1. Compare the generated hash value, to the previously returned hash value.

Validate the integrity of the webhook (Version 2)

Using HMAC_SHA256 significantly boosts security and simplifies the way we verify webhooks for you. This method is an industry standard, a well-supported and trusted way to protect your data. Instead of our previous more complex process, HMAC_SHA256 involves a single, robust cryptographic function applied to the entire JSON message sent to your webhook URL, streamlining the integration process.

Follow the below steps to calculate the hash value:

  1. Obtain the JSON payload message from the posted webhook and append your app_key.
"app_key", {"webhook_type": "status_update", "webhook_id": "bc25b699-ffb1-40d5-b508-f6a28aeb18eb", "timestamp": 32908394083, "webhook_body": {"transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0", "status": "cancelled", "order_id": "6234ae00-1352-4bd7-872a-f328df1b7096" }}"
  1. HMAC_SHA256 encrypt the resulting string.

bece0bdfcfcb96364e31c653d115731545c3d2a8cdbde73aedff2b085117c30e

  1. Compare the generated hash value, to the previously returned hash value.

Webhook structure

There has also been a small change to the structure of webhooks, the timestamp has been moved outside of the webhook_body object and also the webhook_id will now always be in lowercase.

Please see a breakdown of each webhook below:

status_update

The status_update webhook provides the merchant with the current status of the payment request.

{
 "webhook_type": "status_update",
 "webhook_id": "bc25b699-ffb1-40d5-b508-f6a28aeb18eb",
 "timestamp": 32908394083,
 "webhook_body": {
   "transaction_id": "1d0483a7-6f84-4784-9fba-3c7553847be0",
   "status": "cancelled",
   "order_id": "6234ae00-1352-4bd7-872a-f328df1b7096"
 }
}

customer_new

When a customer_reference is provided in the Hosted Checkout request, a customer_new webhook containing the customer_id will be provided when a payment request is made.

{
  "webhook_type": "customer_new",
  "webhook_id": "3e22ae7a-3d4d-47d7-99d0-67ecb3db781c",
  "timestamp": 1684254231,
  "webhook_body": {
    "transaction_id": "",
    "status": "success",
    "order_id": "J97C6572ddt223-952",
    "customer_id": "0dbc3d71-4015-d9f6-633e-9b8290986927"
  }
}

card_new

When a customer's card details used in the Hosted Checkout are saved, the card_new webhook will be sent containing the card_id. Card IDs are only created if the payment request is successful.

{
  "webhook_type": "card_new",
  "webhook_id": "d68a7a29-47ce-43ea-bad3-0e4a35c5f09c",
  "timestamp": 1684254231,
  "webhook_body": {
    "transaction_id": "0e789cf6-7e7a-3c55-870c-e69325975134",
    "status": "success",
    "order_id": "J97C6572ddt223-952",
    "card_id": "77e595b6-686b-724b-6340-6c8ee0123778"
  }
}

funds_received

When an inbound payment is received into an Acquired account. 

{
   "webhook_type":"funds_received",
   "webhook_id":"222ddd53-3032-54e4-792c-95262f69d40b",
   "timestamp":1690897080,
   "webhook_body":{
      "transaction_id":"77ddf76d-54f9-b3b1-7c84-770494246e43",
      "status":"success",
   },
   "transaction":{
      "amount":14.99,
      "currency":"gbp"
   },
   "payment":{
      "reference":"Inbound Payment"
   },
   "payer":{
      "account_name":"Richard Murphy",
      "account_number":"123456",
      "sort_code":"12345678"
   }
}