Overview

📘

What are Webhooks?

Webhooks are automated notifications sent from BizFlex Africa to your server whenever a specific event occurs (like a successful payment or a status change), ensuring your system stays in sync without constant manual polling.

Typically, when you send an API request, you expect an immediate response. However, some processes take time to finalize. To prevent timeout errors, BizFlex returns an initial "pending" status. To get the final outcome, you need a Webhook Listener that automatically receives the final response once the transaction is processed.

How to Create a Webhook URL

A webhook URL is a dedicated POST endpoint on your server designed to receive data payloads from our resource server.

JavaScript

// Example using Express.js
app.post("/bizflex/webhook-listener", function(req, res) {
    // Retrieve the event data from the request body
    const event = req.body;

    // Process the event logic here
    console.log("Received BizFlex event:", event.type);

    // Always acknowledge receipt promptly
    res.sendStatus(200);
});

Your server must acknowledge receipt of the event by returning an HTTP 200 OK status. If BizFlex does not receive this confirmation, our system will assume the delivery failed and will continue to retry based on the following schedule:

• Live Mode: Retries every 3 minutes for the first 4 attempts, then switches to hourly retries for the next 72 hours.
• Test Mode: Retries hourly for the next 72 hours.

🚧

Pro-Tip: Avoid Long-Running Tasks

If your logic involves heavy processing (like generating PDFs or complex database syncing), acknowledge the event first (return 200 OK) and then execute your task. If your server takes too long to respond, BizFlex will time out and trigger the retry logic.

---

Using Your Webhook URL

Ready to go live? Use this checklist to ensure your integration is seamless:

• Register the URL: Add your webhook endpoint in the BizFlex Merchant Dashboard settings.
• Public Accessibility: Ensure your URL is public (Note: localhost will not work; use a tool like Ngrok for local testing).
• Format Handling: If using .htaccess, remember to include the trailing slash (/) in your URL to avoid redirect issues.
• Verification: Test the endpoint to confirm you are correctly parsing the JSON body and returning a 200 OK header.
• Asynchronous Processing: If your function handles long tasks, return the 200 OK status before running those tasks.
• Retry Awareness: Understand that any response other than 200 OK is flagged as a failure and will trigger our automated retry system.

---