> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onnucleus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & Event Streaming

> Real-time asynchronous notification of ledger and transaction events.

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

```json theme={null}
{
  "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:

```bash theme={null}
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
}
```