Webhook

Info

webhooks allow you to set up a notification system that can be used to receive updates on payment requests made to the Chipdeals API.

Introduction

Generally, when you make a request to an API URL, you expect to get an almost immediate response. However, some requests may take a long time to process or require user action before being validated, which may result in timeout errors.

In order to avoid these timeout errors, a temporary response is returned. Since your queries need to be updated with the final status of the query, you must either:

✓ Continuously query our servers to check the status of requests (commonly called polling) or,

✓ Listen for update events using a webhook URL.

Info

We recommend that you use the webhook to bring value to your customers rather than using polling. With polling you trigger a huge resource expenditure and risk having errors in case of disruption of the connection.

Polling vs Webhooks

Polling requires doing a GET request at regular intervals to get the final status of a request. For example, when a customer makes a payment for a transaction, you continue to request the status of the transaction until you get a successful transaction status.

With webhooks, the resource server (Chipdeals in this case), sends updates to your server when the status of your requests changes (updating your payment status in this case) . The change of status of a request is called an event (events). You will typically listen for these events on a POST endpoint called Webhook URL.

The table below highlights some differences between polling and webhooks:

	Polling	Webhooks
Update mode	Manual	Automatic
Efficient with scale	No	Yes

Create a webhook url

A Webhook Url is simply a URL to which a server sends updates by POST. Upon receiving a POST request on this URL, the receiver must parse the JSON data and return a 200 OK status.

To create a webhook URL, simply create a POST endpoint and submit the URL of this endpoint during a payment request. In the management code of this endpoint, a process must be prepared for receiving an update request.

NodeJs

// Avec expressapp.post("/my/webhook/url", function (req, res) {  const requestBody = req.body; // Recovery of the body during a status update  res.send(200); // Reply to Chipdeals that the webhook is processed  // Reply to Chipdeals that the webhook is processed  const transaction = JSON.parse(requestBody.transaction);  console.log(transaction);  // View transaction status  if (transaction.status == "success") {    // Run a code  }});

Laravel

use \Chipdeals\MomoApi\Momo;//...Route::post('/my/webhook/url', function () {  $momo = new Momo();  // Recovery of the body during a status update  $jsonBody = file_get_contents('php://input');  $requestBody = json_decode($jsonBody, true);  // Reply to Chipdeals that the webhook is processed  http_response_code(200); // PHP 5.4 or higher  // Transaction Recovery  $transaction = $momo->parseWebhookData($requestBody);  // View transaction status  if($transaction->getStatus() == "success")  {    // Run a code  }}

PHP

require_once("path/to/chipdeals-mobile-money-api.php");$momo = new Momo();// Recovery of the body during a status update$jsonBody = file_get_contents('php://input');$requestBody = json_decode($jsonBody, true);// Reply to Chipdeals that the webhook is processedhttp_response_code(200); // PHP 5.4 or higher// Transaction Recovery$transaction = $momo->parseWebhookData($requestBody);// View transaction statusif($transaction->getStatus() == "success"){  // Run a code}

When your webhook URL receives an event, it should parse and return a receive response. Acknowledging an event means returning a 200 OK status in the HTTP response header.

Avoid long tasks

If you have long-running tasks in your webhook receive function, you must respond that you have received the data before executing the long-running tasks. Long-running tasks will cause our request to time out and an automatic error response from your server.

Check the origin of the event

Since your webhook URL is publicly available, you need to verify that the events are coming from Chipdeals and not a malicious user. There is a way to ensure that your webhook URL events are coming from Chipdeals:

IP Authorization

With this method, you allow only certain IP addresses to access your webhook URL while blocking others. Chipdeals will only send webhooks from the following IP addresses:

178.238.232.232

You must whitelist this IP address and treat requests from other IP addresses as forgery.

Body of the webhook

All webhook events follow the same basic structure:

• a title property describing the type of event
• a transaction property. It contains the Transaction object. The object will usually contain details about anything related to the transaction that changed state. So we find there:
  • a reference property containing the transaction identifier
  • a status property describing the status of the transaction. Possible values are success, pending or error
  • a statusMessageCode property containing a specific code that identifies an exact status of the transaction. See the list of statusMessageCode
  • a statusMessage property, containing an understandable description of the exact status of the transaction
  • and many other data. See an example below

Example

{
  "title": "transaction state changed",
  "transaction": {
    "reference": "95bd598e-7ef5-4e48-96df-0867eb702b4b",
    "senderPhoneNumber": "22951010580",
    "senderCountryCode": "BJ",
    "senderOperator": "MTN",
    "senderFirstName": "Iyam",
    "senderLastName": "EVERICH",
    "originalCurrency": "XOF",
    "currency": "XOF",
    "status": "pending",
    "statusMessage": "Waiting for user validation",
    "statusMessageCode": 204,
    "startTimestampInSecond": 1663461737,
    "endTimestampInSecond": 0,
    "amount": 1,
    "originalAmount": 1,
    "transactionType": "payment"
  }
}