Webhooks & Event Streaming - Nucleus Core Banking

Nucleus emits webhook notifications whenever ledger states change. Webhooks ensure your core banking engine and client applications stay in sync without aggressive polling.

Supported Events

Event Name	Description
`account.credit`	Inbound deposit, cash-in, or inter-bank NIP transfer settled
`account.debit`	Outbound transfer, withdrawal, or fee applied
`loan.approved`	Loan passed maker-checker appraisal and approval
`loan.disbursed`	Funds transferred to borrower’s operating account
`client.created`	Customer onboarded with CIF assigned
`bvn.duplicate_detected`	AML compliance flag: BVN mapped to another active profile

Webhook Payload Structure

{
  "eventId": "evt_9f81a7b6c5d4",
  "eventType": "account.credit",
  "timestamp": "2026-09-12T11:00:00Z",
  "tenantId": "pilot-mfb",
  "data": {
    "accountId": 12,
    "accountNo": "0123456789",
    "clientId": 1,
    "cif": "CIF00000001",
    "amount": 150000.00,
    "currency": "NGN",
    "runningBalance": 450000.00,
    "reference": "NIP-20260912-00912384",
    "originator": {
      "bankName": "Access Bank",
      "accountNo": "0012345678",
      "senderName": "Kalu Jude"
    }
  }
}

Registering a Webhook Endpoint

Webhooks are configured via the Staff Console or using the Corebanking Hooks API:

POST /nucleus/api/v1/hooks?tenantIdentifier=pilot-mfb
Content-Type: application/json

{
  "name": "SMS & Push Notification Service",
  "isActive": true,
  "displayName": "Customer Notifications",
  "events": [
    { "actionName": "CREATE", "entityName": "SAVINGSACCOUNT" },
    { "actionName": "DEPOSIT", "entityName": "SAVINGSACCOUNT" },
    { "actionName": "WITHDRAWAL", "entityName": "SAVINGSACCOUNT" }
  ],
  "config": {
    "Payload URL": "https://api.yourbank.com/webhooks/nucleus",
    "Content Type": "json",
    "Secret": "whsec_live_9f823a10e7b44c8d"
  },
  "templateId": 1
}