Webhooks

---

Overview

• For Woocommerce users, our plugin configures all the integration without any further action. All you need to do is input your API KEY in the plugin Settings page.

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 callback URL you provided on the Fliz Pay 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.

• When you obtain the Secret, our server will try to test the webhook endpoint that you have provided.
• Make sure that it has a rule for when the body is {test: true} and answer properly with {success: true, data: { alive: true }}

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, the request will be considered invalid and discarded.

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

const { createHmac } = require('crypto');
const config = require('../config');

/*
  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.
*/
function validateRequest(req, res, next) {
  const secret = env.FLIZ_WEBHOOK_SIGNING_SECRET;
  const data = req.body;
  const expectedSignature = sign(data, secret);

  const signature = req.get('X-Fliz-Signature');

  if (signature !== expectedSignature) throw new Error('invalid signature!');

  next();
}

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

Webhook Payload

When a transaction is processed, Fliz sends a webhook notification with a payload that includes detailed information about the payment. An example of the structure of the response body is as follows:

{
  "transactionId": "123456789",
  "status": "completed",
  "amount": 100.00,
  "currency": "USD",
  "timestamp": "2024-05-15T12:00:00Z",
  "metadata": {
    "customerId": "987654321",
    "orderId": "111222333"
  }
}

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.