Webhooks

📘

In a nutshell

Webhook allows you to set up a notification system that ca be used to receive updates on certain request made to the Pandascrow 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. Since your records need to be updated with the final state of the request, you need to listen to events by using a webhook URL.

Create a Webhook URL

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
?>

Node

// 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);
});

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:

1. In live mode, we’ll send webhooks every 3 minutes for the first 4 tries, then we switch to sending hourly for the next 72 hours
2. In test mode, we send webhooks hourly for the next 72 hours

Verify Event Origin

Since your webhook URL is publicly available, you need to verify that events originate from Pandascrow and are not bad actors. There are two ways to ensure events to your webhook URL are from Pandascrow:

1. Signature validation
2. IP whitelisting

Supported events

Successful Virtual Account

{
  "event": "success.virtual.account",
  "data": {
    "userID": 1,
    "businessID": 1,
    "currency": "NGN",
    "accountType": "individual",
    "bankcode": "058",
    "accountNumber": "4444444444",
    "accountName": "JOHN DOE",
    "customer_code": "PS_0f3iv4y8w30z0ubkk2p3i0r0lcploqkm",
    "reference": "REF_79jf081gsb7m4drtphiiihyzfbqscp55",
    "dateCreated": "Fri, 16 Jun 2023 12:32:59 +0000"
  }
}