Webhooks

---

Overview

Fliz uses webhooks to deliver real-time updates on payment statuses. When you initiate a transaction using the Fliz payments API, Fliz will send a webhook notification to the Webhook URL you provided on the FLIZ Integrations Dashboard. This notification will inform you whether the user has successfully completed the transaction or if the transaction has failed.

Security & Signature

All requests sent to your endpoints will need a handshake with our servers. To ensure that the request is authentic and originating from Fliz, you must verify the value of this header. Follow these steps to validate the signature:

1- Obtain the Webhook Signing Secret: Log in to the Fliz Integrations Dashboard and retrieve the Webhook Signing Secret from your Fliz Integrations Dashboard.

2- Calculate a new signature for the request: The signature is calculated using the request body and the Webhook Signing Secret. Use the HMAC (Hash-based Message Authentication Code) algorithm with SHA-256 hash function to generate the signature.

3- Validate the Signature: If the calculated signature matches the value of the X-Fliz-Signature header, the request is considered authentic and originated from Fliz. If the signatures do not match, you need to consider the request invalid and discard it.

Here's a code example demonstrating the signature validation process using Node.js:

const { createHmac, timingSafeEqual } = require('crypto');

/*
  This middleware validates the request body against the X-Fliz-Signature header.
  If the signature is invalid, an error is thrown.
  If the signature is valid, the next middleware is called.

  ✨  The comparison uses crypto.timingSafeEqual to prevent
      timing attacks that could leak signature bytes.
*/
function validateRequest(req, res, next) {
  const secret = process.env.FLIZ_WEBHOOK_SIGNING_SECRET;
  const data = req.body;

  const expectedSignature = sign(data, secret);
  const signature = req.get('X-Fliz-Signature') || '';

  // Convert both signatures to Buffers of equal length
  const expected = Buffer.from(expectedSignature, 'hex');
  const supplied  = Buffer.from(signature,          'hex');

  const valid =
    expected.length === supplied.length &&  // lengths must match
    timingSafeEqual(expected, supplied);    // constant-time compare

  if (!valid) throw new Error('invalid signature!');

  next();
}

/*
  Parameter "data" is the request / response body.
  The response is the X-FLIZ-SIGNATURE.
*/
function sign(data, secret) {
  return createHmac('sha256', secret)
           .update(JSON.stringify(data))
           .digest('hex');
}

Webhook Payload

When a transaction is processed, Fliz sends a webhook notification with a payload that includes detailed information about the payment. The webhook payload contains the following fields:

Field	Type	Description
transactionId	string	Unique Fliz identifier for the transaction
status	string	Current status of the transaction. Possible values: completed, failed, canceled
amount	string	Final amount after discounts (formatted to 2 decimal places)
originalAmount	string	Original transaction amount before discounts (formatted to 2 decimal places)
currency	string	Currency code for the transaction
timestamp	number	Current timestamp in milliseconds when the webhook is generated
metadata	object	Additional transaction metadata
metadata.customerId	string	Customer identifier (primarily for WooCommerce, can be overwritten by custom metadata)

Example webhook payload:

{
  "transactionId": "123456789",
  "status": "completed",
  "amount": "95.00",
  "originalAmount": "100.00",
  "currency": "EUR",
  "timestamp": 1672531200000,
  "metadata": {
    "customerId": "customer_456"
  }
}

Your Webhook Response

To acknowledge the receipt of a webhook notification, your endpoint should respond with a 200 OK HTTP status code. This response should be sent as soon as your system successfully processes the incoming webhook without any errors. If Fliz does not receive a 200 response, it will attempt to resend the webhook notification.