If you enable webhook notifications and set a webhook URL, Safe Haven will send webhook events to notify updates, transfers, transactions.
| Event | eventType / type | When it is sent | Sent to |
|---|---|---|---|
| Account credit | account.credit / transfer | Money is received into an account or sub-account. | Sub-account callbackUrl, or your dashboard webhook URL. |
| Account debit | account.debit / transfer | An outgoing transfer is created (status usually Created). | Sub-account callbackUrl, or your dashboard webhook URL. |
| Outward transfer result | outward.transfer / transfer.outward | An outgoing transfer reaches its final result (Completed or Reversed). | Your dashboard webhook URL. |
| Virtual account payment | no eventType / virtualAccount.transfer | Money is paid into a virtual account. | That virtual account's callbackUrl. |
Webhook Account Credit
{
"eventType": "account.credit",
"type": "transfer",
"data": {
"queued": false,
"limitExceeded": false,
"_id": "6ac3d2f75677120024d9b573",
"client": "695b887f5877190024248935",
"account": "6985f82373894e0024892867",
"type": "Inwards",
"sessionId": "100033261005164021958568653551",
"nameEnquiryReference": "100033261005164008621675730778",
"paymentReference": "100033261005164021958568653551",
"mandateReference": null,
"isReversed": false,
"reversalReference": null,
"provider": "NIBSS",
"providerChannel": "NIP",
"providerChannelCode": "3",
"destinationInstitutionCode": "090286",
"creditAccountName": "ACME LTD / JOHN DOE",
"creditAccountNumber": "0000000000",
"creditBankVerificationNumber": null,
"creditKYCLevel": "3",
"debitAccountName": "ACME LTD",
"debitAccountNumber": "0000000000",
"debitBankVerificationNumber": null,
"debitKYCLevel": "3",
"transactionLocation": "",
"narration": "JOHN DOE:0000000000",
"amount": 100,
"fees": 5,
"vat": 0.38,
"stampDuty": 0,
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"status": "Completed",
"isDeleted": false,
"createdAt": "2026-10-05T16:40:23.617Z",
"updatedAt": "2026-10-05T16:41:24.067Z",
"approvedAt": "2026-10-05T16:41:24.067Z"
}
}
Webhook Account Debit
{
"eventType": "account.debit",
"type": "transfer",
"data": {
"queued": false,
"limitExceeded": false,
"_id": "69ca80284b70e6002412d9de",
"client": "6874eb47aaad890024be3930",
"account": "6874eb48aaad890024be3931",
"type": "Outwards",
"sessionId": "999240260330135240846606296310",
"nameEnquiryReference": "999240260330135232160661808196",
"paymentReference": "SHW-300326145239643",
"mandateReference": null,
"isReversed": false,
"reversalReference": null,
"provider": "BANK",
"providerChannel": "TRANSFER",
"providerChannelCode": "IBS",
"destinationInstitutionCode": "999240",
"creditAccountName": "ACME LTD / SETTLEMENT ACCOUNT",
"creditAccountNumber": "0000000000",
"creditBankVerificationNumber": null,
"creditKYCLevel": "3",
"debitAccountName": "ACME LTD",
"debitAccountNumber": "0000000000",
"debitBankVerificationNumber": null,
"debitKYCLevel": "3",
"transactionLocation": "9.0932,7.4429",
"narration": "",
"amount": 1000,
"fees": 0,
"vat": 0,
"stampDuty": 0,
"responseCode": null,
"responseMessage": null,
"status": "Created",
"isDeleted": false,
"createdAt": "2026-03-30T13:52:40.616Z",
"createdBy": "6874eaf8aaad890024be3912",
"updatedAt": "2026-03-30T13:52:40.616Z"
}
}
Webhook Outward Transfer Result
Sent when an outgoing transfer is final. Use data.status (Completed or Reversed) to update your records; account.debit is sent earlier, when the transfer is created.
{
"eventType": "outward.transfer",
"type": "transfer.outward",
"data": {
"_id": "6650a1f2c3d4e5f6a7b8c9d2",
"client": "650ef86304bf995cd02371d1",
"account": "65ee3e6455861097b509520d",
"type": "Outwards",
"sessionId": "090286251113121500123456789014",
"nameEnquiryReference": "090286251113121455987654321100",
"paymentReference": "ACME-TRF-000125",
"mandateReference": null,
"isReversed": false,
"reversalReference": null,
"provider": "NIBSS",
"providerChannel": "NIP",
"providerChannelCode": "3",
"destinationInstitutionCode": "000013",
"creditAccountName": "JOHN DOE",
"creditAccountNumber": "0123456789",
"creditBankVerificationNumber": null,
"creditKYCLevel": "3",
"debitAccountName": "ACME LTD",
"debitAccountNumber": "0100000011",
"debitBankVerificationNumber": null,
"debitKYCLevel": "3",
"transactionLocation": "9.0932,7.4429",
"narration": "Invoice 125",
"amount": 5000,
"fees": 10,
"vat": 0.75,
"stampDuty": 0,
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"status": "Completed",
"isDeleted": false,
"createdAt": "2026-11-13T12:15:00.123Z",
"updatedAt": "2026-11-13T12:15:20.456Z",
"approvedAt": "2026-11-13T12:15:20.456Z"
}
}
Webhook for Transfer to Virtual Account
Sent to the virtual account's callbackUrl. It has no eventType. metadata is the object you set when you created the virtual account.
{
"type": "virtualAccount.transfer",
"data": {
"_id": "65b76ed3c0a4440024e45e75",
"client": "61e5a83ac6f0ec001ee90fac",
"virtualAccount": "65b76ebbc0a4440024e45e52",
"sessionId": "999240240129092434550231308787",
"nameEnquiryReference": "999240240129092425585215261320",
"paymentReference": "999240240129092434550231308787",
"isReversed": false,
"reversalReference": "",
"provider": "BANK",
"providerChannel": "TRANSFER",
"providerChannelCode": "IBS",
"destinationInstitutionCode": "999240",
"creditAccountName": "ACME LTD / JOHN DOE",
"creditAccountNumber": "0000000000",
"creditBankVerificationNumber": null,
"creditKYCLevel": "3",
"debitAccountName": "ACME LTD",
"debitAccountNumber": "0000000000",
"debitBankVerificationNumber": null,
"debitKYCLevel": "3",
"transactionLocation": "9.0932,7.4429",
"narration": "",
"amount": 100,
"fees": 5,
"vat": 0,
"stampDuty": 0,
"responseCode": "00",
"responseMessage": "Approved or completed successfully",
"status": "Completed",
"isDeleted": false,
"createdAt": "2024-01-29T09:24:35.910Z",
"updatedAt": "2024-01-29T09:24:37.994Z",
"metadata": {
"orderId": "ORD-1001"
}
}
}
Receiving webhooks
- Respond with HTTP 200 as quickly as possible, then process the event.
- Webhooks are not signed. Before you give value, confirm the transaction with Transfer Status or Get Virtual Transaction.
- You may receive the same event more than once. Use
data.sessionIdto ignore duplicates.