Webhook events
This page lists the events you can subscribe to and the payload each one carries. For setup, signatures and retries see Webhooks.
Subscribable events
Pick these per endpoint in the portal under Integrations → Webhooks.
| Event | Fires when |
|---|---|
deposit.transaction.completed | A deposit into your company succeeded. |
deposit.transaction.failed | A deposit failed or was cancelled. |
deposit.transaction.settled | A captured card payment was settled by the acquirer into your float. |
disburse.transaction.completed | A payout from your company succeeded. |
disburse.transaction.failed | A payout failed or was cancelled. |
bill.validation | A paybill payment is about to be taken and we ask you to accept or decline it. Details. |
An endpoint with no events selected receives every notification event above, except bill.validation, which an endpoint only receives when it names it. webhook.test is always delivered.
Event name versus event type
Two names travel with each delivery, and it helps to know which is which.
| Example | Where | Use it for | |
|---|---|---|---|
| Event type | transaction.completed | eventType in the body and X-Webhook-Event header | Long-standing name. Existing receivers keep working on it. |
| Event name | deposit.transaction.completed | metadata.event in the body | The name you subscribe to. Tells you whether money came in or went out. |
If your endpoint receives both deposits and payouts, branch on metadata.event, or on data.type.
The data object
Completed, failed and settled events all carry the transaction in data.
| Field | Description |
|---|---|
id | The transaction id. For an invoice this is the transactionId returned at creation. |
type | The kind of transaction, for example STK_PUSH, B2C, B2B, C2B, BANK_TRANSFER, BANK_DEPOSIT, AIRTEL_COLLECTION, AIRTEL_PAYOUT, REVERSAL, WEBHOOK. |
status | COMPLETED, FAILED, PENDING or AWAITING_SETTLEMENT. |
amount, currency | The amount and currency. |
accountReference | The reference you supplied. |
invoiceNo | Your company's identifier letters followed by the accountReference. |
externalId | The externalId you supplied. Empty if you did not send one. |
transactionDesc | The description you supplied. |
phoneNumber, accountNumber | The counterparty's phone number or account. |
counterPartyName | The counterparty's name, when known. |
bankName, bankCode, partyBType | Bank and destination details, for bank and business payouts. |
receiptNumber | The rail's receipt, for example the M-Pesa code or the card acquirer's receipt. Store it against your order. |
resultCode, resultDesc | The rail's result. |
errorMessage | A human-readable reason when status is FAILED. |
createdAt, updatedAt, transactionDate | Timestamps. |
companyId | Your company id. |
Examples
Completed deposit
{
"id": "0b0e9a3c-8f1d-4a7b-b1a2-3c4d5e6f7a8b",
"eventType": "transaction.completed",
"timestamp": "2026-07-18T09:15:00.000Z",
"data": {
"id": "a3f1c2d4-5e6b-7a8c-9d0e-1f2a3b4c5d6e",
"type": "STK_PUSH",
"status": "COMPLETED",
"amount": 1500,
"currency": "KES",
"accountReference": "INV-1001",
"invoiceNo": "ABCINV-1001",
"externalId": "order_8f3a",
"counterPartyName": "Jane Doe",
"receiptNumber": "SGL1234ABC",
"resultCode": "0",
"errorMessage": ""
},
"metadata": { "event": "deposit.transaction.completed" }
}
Failed payout
{
"id": "5c7d9e1f-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
"eventType": "transaction.failed",
"timestamp": "2026-07-18T10:02:00.000Z",
"data": {
"id": "WDR1A2B3C4D5E6F7",
"type": "B2C",
"status": "FAILED",
"amount": 100,
"accountReference": "Account123",
"externalId": "your-transaction-id",
"errorMessage": "The initiator information is invalid."
},
"metadata": { "event": "disburse.transaction.failed" }
}
Card payment sequence
A card payment resolves while the customer is on the page, but the money reaches your float later, when the acquirer settles it. You receive:
| Moment | eventType | metadata.event | data.status |
|---|---|---|---|
| Card approved | transaction.completed | deposit.transaction.completed | AWAITING_SETTLEMENT |
| Acquirer settles | transaction.settled | deposit.transaction.settled | COMPLETED |
| Acquirer settles | transaction.completed | deposit.transaction.completed | COMPLETED |
The last row is kept so older integrations keep working. New integrations should ignore it and act on transaction.settled. Because of it, de-duplicate on data.id plus eventType plus data.status, not on data.id and eventType alone. See Card payments.
Test event
{
"id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
"eventType": "webhook.test",
"timestamp": "2026-07-18T09:00:00.000Z",
"data": {
"message": "This is a test webhook",
"timestamp": "2026-07-18T09:00:00.000Z"
},
"metadata": {}
}
Bill validation
bill.validation is different from the other events because it is a question, not a notification. When a customer pays your paybill, M-Pesa gives us a few seconds to say whether the payment may proceed, and we pass the question to your endpoint.
- Reply
2xxto accept. A2xxthat says nothing in particular counts as acceptance. - Reply with any other status to decline. You can include
resultCodeandresultDescin the JSON body to choose the message the payer sees. - Answer quickly. The request times out after a few seconds, and a timeout or error declines the payment, because accepting money you cannot account for is the worse outcome.
- Only one endpoint can own
bill.validation, and an endpoint only receives it when you select it.
If no endpoint takes bill validation, payments are checked against our own rules instead.
Related
- Webhooks: endpoints, signatures, delivery log and resend
- Direct payments & payouts: the transactions these events describe