Skip to main content

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.

EventFires when
deposit.transaction.completedA deposit into your company succeeded.
deposit.transaction.failedA deposit failed or was cancelled.
deposit.transaction.settledA captured card payment was settled by the acquirer into your float.
disburse.transaction.completedA payout from your company succeeded.
disburse.transaction.failedA payout failed or was cancelled.
bill.validationA 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.

ExampleWhereUse it for
Event typetransaction.completedeventType in the body and X-Webhook-Event headerLong-standing name. Existing receivers keep working on it.
Event namedeposit.transaction.completedmetadata.event in the bodyThe 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.

FieldDescription
idThe transaction id. For an invoice this is the transactionId returned at creation.
typeThe kind of transaction, for example STK_PUSH, B2C, B2B, C2B, BANK_TRANSFER, BANK_DEPOSIT, AIRTEL_COLLECTION, AIRTEL_PAYOUT, REVERSAL, WEBHOOK.
statusCOMPLETED, FAILED, PENDING or AWAITING_SETTLEMENT.
amount, currencyThe amount and currency.
accountReferenceThe reference you supplied.
invoiceNoYour company's identifier letters followed by the accountReference.
externalIdThe externalId you supplied. Empty if you did not send one.
transactionDescThe description you supplied.
phoneNumber, accountNumberThe counterparty's phone number or account.
counterPartyNameThe counterparty's name, when known.
bankName, bankCode, partyBTypeBank and destination details, for bank and business payouts.
receiptNumberThe rail's receipt, for example the M-Pesa code or the card acquirer's receipt. Store it against your order.
resultCode, resultDescThe rail's result.
errorMessageA human-readable reason when status is FAILED.
createdAt, updatedAt, transactionDateTimestamps.
companyIdYour 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:

MomenteventTypemetadata.eventdata.status
Card approvedtransaction.completeddeposit.transaction.completedAWAITING_SETTLEMENT
Acquirer settlestransaction.settleddeposit.transaction.settledCOMPLETED
Acquirer settlestransaction.completeddeposit.transaction.completedCOMPLETED

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 2xx to accept. A 2xx that says nothing in particular counts as acceptance.
  • Reply with any other status to decline. You can include resultCode and resultDesc in 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.