Disburse Webhooks
Last updated Sep 12th, 2025
Overview
Webhooks are used to notify your application of asynchronous events in the Disburse API, such as successful transfers. This page details all available webhook events, their payloads, and best practices for verification and handling.
Prerequisites
Before you begin to receive webhooks, you must:
- Create a POST endpoint on your server and configured a webhook URL in the Mono Partner Dashboard.
- Always validate the webhook request. Add code to your endpoint to validate the request with the webhook secret key, process the event, and return the appropriate response.
Webhooks
Here are all the available webhook events.
- Disbursement Processing
- Disbursement Cancelled
- Disbursement Completed
- Disbursement Transaction Successful
- Disbursement Transaction Failed
- Disbursement Account Created
- Disbursement Account Approved
- Disbursement Account Enabled
- Disbursement Account Disabled
Disbursement Processing
This is sent when a disbursement is initiated.
Request
123456789101112
{
event: "events.disbursement.processing"
data: {
status: "processing"
message: "Disbursement is currently in processing state, please wait for a final state webhook before giving value"
data: {
reference: "DRF_230901ABCD124"
app: "645a0b9e8c7d4e5f6a7b8c9d"
business: "645a0b9e8c7d4e5f6a7b8c9e"
}
}
}
Disbursement Cancelled
This is sent when a disbursement has been cancelled, after calling the transition disbursement endpoint.
Request
123456789101112
{
event: "events.disbursement.cancelled"
data: {
status: "cancelled"
message: "Disbursement has been cancelled."
data: {
reference: "DRF_230901ABCD124"
app: "645a0b9e8c7d4e5f6a7b8c9d"
business: "645a0b9e8c7d4e5f6a7b8c9e"
}
}
}
Disbursement Completed
This is sent when an instant or scheduled disbursement has been completed.
Request
123456789101112131415161718192021222324
{
event: "events.disbursement.completed"
data: {
status: "completed"
message: "Disbursement has been successfully completed."
data: {
reference: "DRF_230901ABCD125"
processing_summary: {
count: 10
amount: 5000000
}
successful_summary: {
count: 9
amount: 4500000
}
failed_summary: {
count: 1
amount: 500000
}
app: "645a0b9e8c7d4e5f6a7b8c9d"
business: "645a0b9e8c7d4e5f6a7b8c9e"
}
}
}
Disbursement Transaction Successful
Request
123456789101112
{
event: "events.disbursement.transaction.successful";
data: {
reference: "DRF_230901ABCD126_TXN1";
status: "successful";
accountNumber: "0123456789";
bank_code: "044";
amount: 500000; // kobo
fee: 5000;
narration: "Payment for services";
}
}
Disbursement Transaction Failed
Request
123456789101112
{
event: "events.disbursement.transaction.failed";
data: {
reference: "DRF_230901ABCD127_TXN2";
status: "failed";
accountNumber: "0987654321";
bank_code: "033";
amount: 100000; // kobo
fee: 1000;
narration: "Insufficient funds";
}
}
Disbursement Account Created
Request
12345678910111213141516
{
"event": "event.disburse.account.created",
"data": {
"account_id": "650e8a7d1b9c2d3e4f5a6b7c",
"account_number": "0123456789",
"bank_code": "044",
"mandate_id": "650e8a7d1b9c2d3e4f5a6b7d",
"status": "created",
"created_at": "2024-01-15T10:30:00.000Z",
"updated_at": "2024-01-15T10:30:00.000Z",
"ready_to_debit": false,
"approved": false,
"app": "645a0b9e8c7d4e5f6a7b8c9d",
"business": "645a0b9e8c7d4e5f6a7b8c9e"
}
}
Disbursement Account Approved
Request
123456789101112131415161718
{
"event": "event.disburse.account.approved",
"data": {
"account_id": "650e8a7d1b9c2d3e4f5a6b7e",
"account_number": "0987654321",
"bank_code": "044",
"mandate_id": "650e8a7d1b9c2d3e4f5a6b7f",
"status": "approved",
"created_at": "2024-01-16T11:00:00.000Z",
"updated_at": "2024-01-16T11:00:00.000Z",
"account_name": "JOHN DOE",
"bank_name": "Zenith Bank",
"ready_to_debit": true,
"approved": true,
"app": "645a0b9e8c7d4e5f6a7b8c9d",
"business": "645a0b9e8c7d4e5f6a7b8c9e"
}
}
Disbursement Account Enabled
Request
123456789101112131415
{
"event": "event.disburse.account.enabled",
"data": {
"account_id": "650e8a7d1b9c2d3e4f5a6b80",
"account_number": "1122334455",
"bank_code": "044",
"status": "enabled",
"created_at": "2024-01-17T12:00:00.000Z",
"updated_at": "2024-01-17T12:00:00.000Z",
"ready_to_debit": true,
"approved": true,
"app": "645a0b9e8c7d4e5f6a7b8c9d",
"business": "645a0b9e8c7d4e5f6a7b8c9e"
}
}
Disbursement Account Disabled
Request
123456789101112131415
{
"event": "event.disburse.account.disabled",
"data": {
"account_id": "650e8a7d1b9c2d3e4f5a6b81",
"account_number": "1122334455",
"bank_code": "044",
"status": "disabled",
"created_at": "2024-01-18T13:00:00.000Z",
"updated_at": "2024-01-18T13:00:00.000Z",
"ready_to_debit": false,
"approved": false,
"app": "645a0b9e8c7d4e5f6a7b8c9d",
"business": "645a0b9e8c7d4e5f6a7b8c9e"
}
}