Webhooks

If you enable webhook notifications and set a webhook URL, Safe Haven will send webhook events to notify updates, transfers, transactions.

EventeventType / typeWhen it is sentSent to
Account creditaccount.credit / transferMoney is received into an account or sub-account.Sub-account callbackUrl, or your dashboard webhook URL.
Account debitaccount.debit / transferAn outgoing transfer is created (status usually Created).Sub-account callbackUrl, or your dashboard webhook URL.
Outward transfer resultoutward.transfer / transfer.outwardAn outgoing transfer reaches its final result (Completed or Reversed).Your dashboard webhook URL.
Virtual account paymentno eventType / virtualAccount.transferMoney 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.sessionId to ignore duplicates.