Webhooks

CreditChek uses Webhooks to communicate updates on requests initiated with our API for you to kick off additional workflows based on these events. Due to credit bureau downtime or services that takes time for a response, CreditChek submits a POST request to the designated Webhook URL with updates about the transaction.

Your endpoint should respond to webhooks as quickly as possible. To acknowledge receipt of a webhook, your endpoint must return a 2xx HTTP status code. This status code should only indicate receipt of the message, not an acknowledgement that it was successfully processed by your system. Any other information returned in the response headers or response body is ignored.

Security

All Webhook requests are sent with a x-auth-signature header for verification. It should match the secret key pair of the app public key you used when initiating the request.

Nodejs Example

// example js implementation
const secret = process.env.CREDITCHEK_SECRET_KEY;

function verifyWebhook(req, res, next) {
  if (req.headers["x-auth-signature"] !== secret) {
    return res.status(401).json({
      message: "Unauthorized request.",
    });
  }
  next();
}

router.post("/webhook", verifyWebhook, (req, res) => {
  const webhook = req.body;
  switch (webhook.event) {
    case "pdf_upload":
    // do something with webhook.data;
    case "borrower_onboarded":
    // do something with webhook.data;
    case "income_insight": 
    // do something with webhook.data;
    case "income_transaction":
    // do something with webhook.data;
    case "credit_premium":
    // do something with webhook.data;
    case "credit_advanced":
    // do something with webhook.data;
      break;
  }
  return res.sendStatus(200);
});

Retries & Failure

In a case where CreditChek was unable to reach the URL, all the webhooks will only be tried once. It's advisable that Webhook URLs respond with a status 200 OK, before carrying one with processing the data in it. To retry a failed webhook you can go to your dashboard audit logs to re-send a webhook.

Sample webhook format

The JSON payload below is a sample response of a webhook event that gets sent to your webhook URL. You should know that all webhook events across CreditChek all follow the same payload format as shown below.

Sample Credit Webhook payload

{
  "event": "credit_premium",
  "data": {
    "score": [Object],
    "bvn": 44550011223,
    "name": "Ndaka Kadir Hassan",
    "_id": "5fbcde8f8699984153e655a0",
    "gender": "Male",
    "dateOfBirth": "20/09/1994",
    "address": "No 1, Chevron Drive, Lagos",
    "phone": 0802,
    "email": "[email protected]",
    "bureauStatus": [Object],
  }
}

Sample Income Webhook payload

{
  "event": "pdf_upload",
  "data": {
    "success": true,
    "pageCount": 14,
    "accountName": "Test Jorm",
    "accountNumber": "7160010613",
    "accountType": "savings",
    "bankName": "fidelity bank",
    "bankCode": "070",
    "pdfUrl": "https://res.creditchek-africa/image/pdfStatement/62877574ae22b03091_070_savings_fidelity%20bank.pdf",
    "bvn": "22357999900",
    "borrowerId": "64c8b66302ed6ac59be6fa44"
  }
}