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',
  merchantReference: 'dev test',
  prescriptionRequired: false,
  status: 'INITIAL',
  updatedAt: null

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

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)
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);

// 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

Last updated