Webhooks

What are Webhooks

Whenever certain transaction actions occur on your Originate integration, we trigger events that your application can listen to. This is where webhooks come in. A webhook is a URL on your server where we send payloads for such events. For example, if you implement webhooks, once a user is successfully created, we will immediately notify your server with a user.created event. Here is a list of events we can send to your webhook URL.

You can specify your webhook URL on your dashboard where we would send POST requests whenever an event occurs.

Here are some things to note when setting up a webhook URL:

Do a test post to your URL to ensure that it receives the expected request
Ensure your webhook URL is publicly available (localhost URLs cannot receive events)

Event Reception

In order to receive an event, create an unauthenticated POST route on your application. The event object is sent as JSON in the request body.

JavaScript

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

Event Verification

It’s important to verify that an event was sent from Originate servers. In order to do this, you need to validate the req.headers[“x-indicina-signature”] with your clientId.

JavaScript

const crypto = require('crypto');
const secret = process.env.CLIENT_ID;
// Using Express
app.post("/my/webhook/url", function(req, res) {
    //validate event
    const hash = crypto.createHmac('md5', secret).update(JSON.stringify(req.body)).digest('hex');
    if (hash === req.headers['x-indicina-signature']) {
    // Retrieve the request's body
    const event = req.body;
    // Do something with event  
    }
    res.send(200);
});

Event Response

You should respond to an event with a 200 OK. We consider this an acknowledgement by your application. If your application responds with any status outside of the 2xx range, we will consider it unacknowledged and thus, continue to send it every hour for 24 hours.

If your application is likely to start a long-running task in response to the event, Indicina may timeout waiting for the response and would ultimately consider the event unacknowledged and queue to be raised later. You can mitigate duplicity by having your application respond immediately with a 200 before it goes on to perform the rest of the task.

Supported Events

Successful Account Creation

JavaScript

{
  status: "success",
  message: "User created",
  eventType: "user.created",
  accountId: "testclientid",
  webhookUrl: "http://yourwebhookurl.com/",
  data: {
    id: "testaccountid"
    status: "active"
    firstName: "test"
    lastName: "account"
    phone: "08xxxxxxxxx"
    email: "test@email.com"
    bvn: "232xxxxxxxx"
    dateOfBirth: "23/04/19xx"
    address?: "optional address"
    state?: "optional state"
    employmentStatus: "employed"
    createdAt: "20201-01-23 13:55:32.588"
  }
}

Successful Loan Application

JavaScript

Successful Loan Creation

JavaScript

Successful Loan Disbursement

JavaScript

Successful Loan Repayment

JavaScript

Successful Debit Card Addition

JavaScript

Successful Repayment Breakdown Updated

JavaScript

List of Events

Event type	Description

Event type	Description
user.created	A user was successfully created on Originate
application.approved	A customer’s loan application has been approved
loan.created	A loan object (portfolio) has been created to track customer’s approved loan
loan.disbursed	The loan amount has been disbursed to the customer’s preferred account
loan.repaid	A repayment was successfully processed for a customer on, before, or after a due date.
card.tokenized	A customer successfully added a debit card.
repaymentbreakdown.updated	The repayment breakdown for a loan has been updated.