Webhooks

CreditChek uses Webhooks to communicate updates on requests initiated with our Income service API for you to kick off additional workflows based on these events. Due to lengthy period it takes for our AI service to successfully process your customer uploaded statement, 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.

Supported Events

pdf_upload

Sample webhook for PDF upload

{
  "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"
  }
}

income_transaction

Sample webhook for Income transaction

{
  "event": "income_transaction",
  "data": {
    "accountNumber": "7160010613",
    "accountName": "TET JORM",
    "bvn": "22357999900",
    "appId": "62877574ae22f30012b03091",
    "borrowerId": "64c8b66302ed6ac59be6fa44",
    "businessId": "6287757348cc6c0013f4d0a0",
    "balance": 55659462,
    "bankCode": "070",
    "bankName": "fidelity bank",
    "createdAt": 1695108973334,
    "pdfUrl": "https://res.cloudinary.com/creditchek.africa/image/pdfStatement/6287757012b03091_070_savings_fidelity%20bank.pdf",
    "lastTransactionDate": "2023-02-23T00:00:00Z",
    "trans": [
      {
        "type": "debit",
        "narration": "ONB TRF TO PAYSTACK C **3992 WEM",
        "amount": 8500000,
        "date": "2023-02-23T00:00:00Z",
        "balance": 55659462,
        "bankCode": "070"
      },
      {
        "type": "debit",
        "narration": "Loan Recovery For - 000303010302753",
        "amount": 2856155,
        "date": "2023-02-23T00:00:00Z",
        "balance": 64159462,
        "bankCode": "070"
      },
      {
        "type": "debit",
        "narration": "ELECTRONIC MONEY TRANSFER LEVY - 20-02-2023",
        "amount": 5000,
        "date": "2023-02-20T00:00:00Z",
        "balance": 38432330,
        "bankCode": "070"
      },
      {
        "type": "debit",
        "narration": "ONB TRF TO Islamiyat **7646 - PLYMFB",
        "amount": 70000,
        "date": "2023-02-19T00:00:00Z",
        "balance": 38937330,
        "bankCode": "070"
      },
      {
        "type": "debit",
        "narration": "ELECTRONIC MONEY TRANSFER LEVY - 15-02-2023",
        "amount": 5000,
        "date": "2023-02-16T00:00:00Z",
        "balance": 41342330,
        "bankCode": "070"
      },
      {
        "type": "credit",
        "narration": "000303010302753 Disbursement Credit",
        "amount": 34000000,
        "date": "2023-02-16T00:00:00Z",
        "balance": 41347330,
        "bankCode": "070"
      },
      {
        "type": "debit",
        "narration": "MTN USSD SESSION FEE 08032219857",
        "amount": 697,
        "date": "2023-02-16T00:00:00Z",
        "balance": 7347330,
        "bankCode": "070"
      },
      {
        "type": "debit",
        "narration": "ONB TRF TO MR LAWRENC **2574 from onyeka UBN",
        "amount": 2500000,
        "date": "2023-02-16T00:00:00Z",
        "balance": 7348725,
        "bankCode": "070"
      },
      {
        "type": "credit",
        "narration": "13TH MONTH PAYMENT 2022",
        "amount": 572715,
        "date": "2022-12-08T00:00:00Z",
        "balance": 579358,
        "bankCode": "070"
      }
    ],
    "success": true
  }
}

income_insight

Sample webhook for a Successful Insight

{
  "event": "income_insight",
  "data": {
    "linkedFinancialAccounts": [
      {
        "isavailable": "false",
        "processed": true,
        "_id": "64a96bbaecb5ee873e9c99d3",
        "accountNumber": "1234567890",
        "appId": "6295e8bacccda600124334c9",
        "borrowerId": "62960184b3e03ed27a973471",
        "businessId": "6295e8b91a4f510013818fc1",
        "currency": "NGN",
        "institution": {
          "name": "accessbank",
          "bankCode": "044",
          "type": "PERSONAL_BANKING"
        },
        "name": "ACER TINSX",
        "pdfUrl": "https://res.cloudinary.com/creditchek-africa/upload/pdfStatement/630c8be8d442344e794_64a64e46817eca20821_044_savings_accessbank.pdf",
        "source": "pdf",
        "type": "savings",
        "updatedAt": "2023-07-08T14:00:24.695Z",
        "balance": "57588664",
        "lastTransactionDate": "2023-02-12T00:00:00.000Z"
      }
    ],
    "avgMonthlyIncome": "81111896.6",
    "totalmoneyReceive": "1216678449",
    "totalmoneySpents": "1162886221",
    "eligibleAmount": "321203110.536",
    "DTI": "",
    "DTI_reason": "Please consider this range a reflection of healthy finances and ability to repay debt. This rating represents a good debt/expense level relative to his/her income, where this borrower most likely has money left over for saving or spending after bills are paid",
    "incomeb4Tax": "",
    "recurringDebt": "",
    "bonusIncome": "",
    "_id": "64a64eb4ecb5ee873ee210e3",
    "borrowerId": "64a64e4681741eca2fd00821",
    "__v": 0,
    "edti": {
      "businessId": "6295e8b91a4f510013818fc1",
      "borrowerId": "62960184b3e03ed27a973471",
      "average_monthly_income": "81111896.6",
      "annual_edti": "30.195136217128805",
      "average_monthly_balance": "171953601.3846154",
      "average_monthly_recurring_debt_expenses": "28259824.230769232",
      "number_of_active_months": "13",
      "average_monthly_edti": "34.84054178899478",
      "balance": {
        "February 2022": 3799158,
        "March 2022": 596089735,
        "April 2022": 313296917,
        "May 2022": 300310253,
        "June 2022": 282203289,
        "July 2022": 163053164,
        "August 2022": 117660777,
        "September 2022": 133136774,
        "October 2022": 88536185,
        "November 2022": 17664283,
        "December 2022": 84047280,
        "January 2023": 78010339,
        "February 2023": 57588664
      },
      "EDTI": {
        "February 2023": 0,
        "January 2023": 7,
        "December 2022": 100,
        "November 2022": 11,
        "October 2022": 11,
        "September 2022": 4,
        "August 2022": 6,
        "July 2022": 83,
        "June 2022": 7,
        "May 2022": 10,
        "April 2022": 100,
        "March 2022": 1,
        "February 2022": 0
      },
      "recurrent_expenses_debt": {
        "February 2023": 201075,
        "January 2023": 5910976,
        "December 2022": 135637788,
        "November 2022": 9011776,
        "October 2022": 9188725,
        "September 2022": 2979413,
        "August 2022": 4882288,
        "July 2022": 67070125,
        "June 2022": 5507774,
        "May 2022": 7908975,
        "April 2022": 118024125,
        "March 2022": 1054275,
        "February 2022": 400
      },
      "recurrent_debt_sum": 367377715,
      "averageMonthlyIncome": "81111896.6",
      "totalMoneyReceive": "1216678449",
      "totalMoneySpent": "1162886221",
      "eligibleAmount": "321203110.536",
      "totalBorrowed": "null",
      "totalOutstanding": "null",
      "totalOverdue": "null",
      "creditInsight": "null",
      "spendingAnalysis": {
        "atm": [0],
        "airtime": [1900000],
        "transfers": [256075],
        "party": [13111825],
        "gambling": [0],
        "titheOffering": [0],
        "rent": [22210751],
        "tv": [0],
        "investment": [3002688],
        "loans": [165067200],
        "education": [0],
        "transport": [7749350],
        "electricity": [23140312],
        "tax": [7249842]
      },
      "airtime": {
        "May 2022": 500000,
        "July 2022": 600000,
        "September 2022": 300000,
        "January 2023": 500000
      },
      "investment": {
        "January 2023": 3002688
      },
      "loans": {
        "March 2022": 51075,
        "April 2022": 85005375,
        "July 2022": 50005375,
        "December 2022": 30005375
      },
      "party": {
        "July 2022": 6455375,
        "September 2022": 151075,
        "October 2022": 6505375
      },
      "rent": {
        "April 2022": 13005375,
        "May 2022": 6702688,
        "November 2022": 2502688
      },
      "transfers": {
        "March 2022": 10000,
        "April 2022": 5000,
        "July 2022": 5000,
        "September 2022": 10000,
        "November 2022": 10000,
        "December 2022": 10000,
        "January 2023": 5000,
        "February 2023": 201075
      },
      "transport": {
        "March 2022": 1000000,
        "May 2022": 702687,
        "June 2022": 702687,
        "August 2022": 170000,
        "September 2022": 1536450,
        "October 2022": 331075,
        "December 2022": 1102688,
        "January 2023": 2002688,
        "February 2023": 201075
      },
      "salary": {
        "narration": [
          "ALPHASEVEN OMNI-SOLUTIONS LIMITED/ACCE LIONEL FOTOGH January salary",
          "ALPHASEVEN OMNI-SOLUTIONS LIMITED/ACCE LIONEL FOTOGH Nov salary",
          "ALPHASEVEN OMNI-SOLUTIONS LIMTED/ACCE LIONEL FOTGH October salary",
          "ALPHASEVEN OMNI-SOLUTIONS LIMITED/ACCE LIONEL FOTOGH August salary",
          "ALPHASEVEN OMNI-SOLUTIONS LIMTED/ACCE LIONEL FOTOGH July salary"
        ],
        "amount": [30000000, 29999999, 30000000, 30000000, 30000000]
      },
      "creditBreakdown": {
        "creditFirstHalf0": {
          "January 2023": 30000000,
          "February 2023": 60000000
        },
        "creditFirstHalf1": {
          "February 2022": 3450,
          "March 2022": 614150000,
          "April 2022": 39000000,
          "June 2022": 60000000
        },
        "creditFirstQuarter0": {
          "January 2023": 30000000,
          "February 2023": 60000000
        },
        "creditFirstQuarter1": {
          "February 2022": 3450,
          "March 2022": 614150000
        },
        "creditFourthQuarter1": {
          "November 2022": 59999999,
          "December 2022": 263525000
        },
        "creditSecondHalf1": {
          "July 2022": 30000000,
          "perDebTrans": "90.09433962264151",
          "negBalDays": "0",
          "aveSweepMonthlyCred": "37",
          "averageDailyBal": "184688466.19761905",
          "maxCredit": "288500000",
          "min_crebit": "3450",
          "meanCredit": "57937069",
          "maxDebit": "166099979",
          "minDebit": "345",
          "meanDebit": "6088409.5340314135"
        }
      }
    },
    "success": true
  }
}

income_insight_failure

Sample webhook for a failed Insight

{
  "event": "income_insight",
  "data": {
    "accountNumber": "0156119467",
    "accountName": "KELLY CHECKERS",
    "bvn": "22241683701",
    "appId": "64aac9d453a97b63508946e7",
    "borrowerId": "65115218423277fb6",
    "businessId": "64aac9d453a9086e3",
    "bankCode": "058",
    "bankName": "gtbank",
    "pdfUrl": "https://res.cloudinary.com/creditchek-africa/image/upload/v1695634740/pdfStatement/64aac9d453a97be7_651153592177f36_058_savings_gtbank.pdf",
    "success": false
  }
}

Income Service Events

Here, we'd be describing the various events that can be triggered by our Income service.

Event	Description
pdf_upload	This notifies you when a PDF statement has been uploaded successfully
income_transaction	This webhook event is sent if it's enabled on the dashboard, it contains the transaction details of a pdf after it has been parsed. It's not a required event to analyze the insights, but it's useful for auditing and record-keeping purposes.
income_insight	This event contains the insight successfully gathered from your customer statement uploaded. This webhook contains all the information gathered from our analysis but you could also call this endpoint To get an existing Insight Data on a successful insight hit.
income_insight_failure	This event returns an error update, should an error occur on our end in the process of analyzing your customer bank statement.