Webhooks

Webhooks are HTTP callbacks that receive notification messages for events. To be able to receive webhook notifications, you must configure your server to listen to incoming HTTP POST messages and register it by passing the URL in the merchantUrls.callback optional body parameter every time you create an order payment.

We sign each notification message that we deliver to your webhook listener. It is your choice to verify this signature.

Events and status codes:

There are several events that trigger a notification:

• an order payment was created (status: INITIAL)

• the order payment was claimed by a user logging into the checkout page (status: CLAIMED)

• an order payment is fulfilled, i.e. payment is processed (status: SETTLED)

• an order payment is denied, i.e. payment is denied (status: DENIED)

• an order payment is waiting fulfilment, i.e. payment is still being processed (status: PENDING)

Notification message:

The notification message contains the order payment, including their specific status at that time:

{
  amount: 30000,
  currency: 'EUR',
  createdAt: '2021-09-30T11:54:04.148Z',
  id: '01FGV8VVYWSKYHGKPPZWMXWN8D',
  merchantReference: 'dev test',
  prescriptionRequired: false,
  status: 'INITIAL',
  updatedAt: null
}

In addition, 3 event headers will aid you in validating the source of the notification:

Event Header	Description
Hi-Api-Signature	asymmetric signature generated by Hi.Health
Hi-Api-Signature-Format	encoding of the signature that you can use in the verification process
Hi-Api-Hash-Algorithm	algorithm used to generate the signature and that you use in the verification process

Verification process:

To generate the signature we use an asymmetric signature algorithm such as RSA with SHA256. We take the body of the notification which we sign with a private key and encode it using the encoding specified in Hi-Api-Signature-Format for http transport thus enabling you to use a public key to verify the webhook.

To get the public certificate, follow this link for Sandbox or this link for Production. You will have to store it and have it accessible during the verification process.

Example of verification using node.js:

// Node.js
import crypto from 'crypto'

const algo = <Hi-Hash-Algorithm value>
const format = <Hi-Signature-Format value>
const signature = <Hi-Signature value>
const publicKey = fs.readFileSync(<path_to_Public_Certificate>, 'utf8')
const orderPayment = <body-of-the-POST-request>

const verifier = crypto.createVerify(algo)
verifier.update(JSON.stringify(orderPayment))
const verificationResult = verifier.verify(publicKey, signature, format)

Example of verification using php:

$headers = getallheaders();

// read the public certificate
$fp = fopen("webhook.crt", "r");
$cert = fread($fp, 8192);
fclose($fp);

// decoding depends on the value of Hi-Api-Signature-Format
$signature = base64_decode($headers['Hi-Api-Signature'])

// Signature verification
$cert_test = openssl_verify($body_post_data, $signature, $cert, OPENSSL_ALGO_SHA256);

if ($cert_test == 1) {
    // Display Success
} elseif ($cert_test == 0) {
    // Display Error
} 

✅ If the verification passes, then you can safely process the notification.

⛔ If the verification fails, you have to discard the notification and inform us at [e-mail].