Webhooks

Webhooks allow you to set up a notification system that can be used to receive updates on certain requests made to the B54 API.

Introduction

Generally, when you make a request to an API endpoint, you expect to get a near-immediate response. However, some requests may take a long time to process, which can lead to timeout errors. In order to prevent a timeout error, a pending response is returned.

Create a webhook URL

A webhook URL is simply a POST endpoint that a resource server sends updates to. The URL needs to parse a JSON request and return a 200 OK:

JavaScript

// Using Express
app.post("/my/webhook/url", function(req, res) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event
    res.send(200);
});

PHP

<?php
    // Retrieve the request's body and parse it as JSON
    $input = @file_get_contents("php://input");
    $event = json_decode($input);
    // Do something with $event
    http_response_code(200); // PHP 5.4 or greater
?>

When your webhook URL receives an event, it needs to parse and acknowledge the event. Acknowledging an event means returning a 200 OK in the HTTP header. Without a 200 OK in the response header, we’ll keep sending events for the next 72 hours.

📘

Note

You can specify your webhook URL in the Webhooks & API keys section on the settings page on the portal.

⚠️

Avoid long-running tasks

• If you have long-running tasks in your webhook function, you should acknowledge the event before executing the long-running tasks. Long-running tasks will lead to a request timeout and an automatic error response from your server. Without a 200 OK response, we retry as described in the paragraph above.

Supported events

Transaction Success

{
  "event": "transaction.success",
  "data": {
    "transactions": [
      {
        "customer_partner_id": "WZYeOZ4XfbdWYU1p",
        "start_date": "2023-06-15T09: 51: 54.746Z",
        "expected_payment_date": "2023-06-18T10: 51: 54+01: 00",
        "type": "Loan",
        "value": 5500,
        "financing_requested": false,
        "amount_financed": null,
        "country_id": "7sYdGtUu59Xq084C",
        "amount_paid": null,
        "transaction_fees": null,
        "status": null,
        "category": null,
        "score": 100,
        "client_id": "CyI6P0uB0bcVFMjf",
        "transaction_reference": "transaction_reference_one",
        "id": "ekMzWgTmV8Jz5h2g",
        "created_at": "2023-06-15T10: 51: 54+01: 00",
        "updated_at": "2023-06-15T10: 51: 54+01: 00"
      }
    ],
    "financings": [{ "transaction_reference_one": [] }]
  }
}

Transaction Failed

{
  "event": "transaction.failed",
  "data": {
    "country_id": "ozEhPDsMIAm2vSCf",
    "transactions": [
      {
        "client": [],
        "transaction_reference": "transaction_reference_one",
        "disbursement_date": "2023-06-15T10:04:50.273Z",
        "expected_payment_date": "2023-06-18T11:04:50+01:00",
        "type": "Loan",
        "amount_payable": 5500,
        "financier": "Others"
      }
    ],
    "financed_transactions": [
      {
        "transaction_reference": "transaction_reference_one",
        "amount": 5000,
        "payments": []
      }
    ],
    "message": { "errorMessage": "An error", "errorReasons": [] }
  }
}

Payment Success

{
  "event": "payment.success",
  "data": [
    {
      "transaction_reference": "transaction_reference_one",
      "amount": 5500
    }
  ]
}

Payment Failed

{
  "event": "payment.failed",
  "data": {
    "payments": [
      {
        "transaction_reference": "transaction_reference_one",
        "amount": 5500
      }
    ],
    "message": {
      "errorMessage": "Invalid Payments",
      "errorReasons": []
    }
  }
}

Transfer Success

{
  "event": "transfer.success",
  "data": {
    "ledger_id": "58f40d53-ace2-454a-b183-3839efcf4b5a",
    "ledger_reference": "9B3JCLPfimy4Kijv",
    "ledger_title": "drawdown withdrawal",
    "ledger_transaction_type": "outflow",
    "ledger_client_transaction_type": "outflow",
    "ledger_amount": 150,
    "ledger_balance": 100823638779.23,
    "ledger_client_balance": 89166.33,
    "ledger_channel": "b54",
    "ledger_payment_date": "2023-06-15T11:42:38.237Z",
    "ledger_meta": {
      "account": {},
      "country": {},
      "client_name": "OKEDELE PROMISE CALEB",
      "webhook_url": "https://03c7-102-69-146-83.ngrok-free.app/v1/webhook/test",
      "client_balance": 89166.33,
      "external_reference": "8i63mjqi8lw4c0o1-e7n"
    },
    "ledger_narration": null,
    "ledger_created_at": "2023-06-15T10:42:39.271Z",
    "ledger_updated_at": "2023-06-15T10:42:39.271Z"
  }
}

Transfer Failed

{
  "event": "transfer.failed",
  "data": {
    "ledger_id": "58f40d53-ace2-454a-b183-3839efcf4b5a",
    "ledger_reference": "9B3JCLPfimy4Kijv",
    "ledger_title": "drawdown withdrawal",
    "ledger_transaction_type": "outflow",
    "ledger_client_transaction_type": "outflow",
    "ledger_amount": 150,
    "ledger_balance": 100823638779.23,
    "ledger_client_balance": 89166.33,
    "ledger_channel": "b54",
    "ledger_payment_date": "2023-06-15T11:42:38.237Z",
    "ledger_meta": {
      "account": {},
      "country": {},
      "client_name": "OKEDELE PROMISE CALEB",
      "webhook_url": "https://03c7-102-69-146-83.ngrok-free.app/v1/webhook/test",
      "client_balance": 89166.33,
      "external_reference": "8i63mjqi8lw4c0o1-e7n"
    },
    "ledger_narration": null,
    "ledger_created_at": "2023-06-15T10:42:39.271Z",
    "ledger_updated_at": "2023-06-15T10:42:39.271Z",
    "message": {
      "errorMessage": "Failed transfer",
      "errorReasons": "Insufficient balance"
    }
  }
}

Transfer Reversed

{
  "event": "transfer.reversed",
  "data": {
    "ledger_id": "58f40d53-ace2-454a-b183-3839efcf4b5a",
    "ledger_reference": "9B3JCLPfimy4Kijv",
    "ledger_title": "drawdown withdrawal",
    "ledger_transaction_type": "outflow",
    "ledger_client_transaction_type": "outflow",
    "ledger_amount": 150,
    "ledger_balance": 100823638779.23,
    "ledger_client_balance": 89166.33,
    "ledger_channel": "b54",
    "ledger_payment_date": "2023-06-15T11:42:38.237Z",
    "ledger_meta": {
      "account": {},
      "country": {},
      "client_name": "OKEDELE PROMISE CALEB",
      "webhook_url": "https://03c7-102-69-146-83.ngrok-free.app/v1/webhook/test",
      "client_balance": 89166.33,
      "external_reference": "8i63mjqi8lw4c0o1-e7n"
    },
    "ledger_narration": null,
    "ledger_created_at": "2023-06-15T10:42:39.271Z",
    "ledger_updated_at": "2023-06-15T10:42:39.271Z",
    "message": {
      "errorMessage": "Reversed transfer",
      "errorReasons": "Insufficient balance"
    }
  }
}

Types of events

Event	Description
transaction.success	A transaction registration has been completed successfully
transaction.failed	A transaction registration has failed
payment.success	A payment registration has been completed successfully
payment.failed	A payment registration has failed
transfer.success	A lockbox transfer has been completed successfully
transfer.failed	A lockbox transfer has failed
transfer.reversed	A lockbox transfer has been reversed