Webhook events - Moflay Documentation

Webhook event types describe what changed in Moflay. Subscribe only to the events your backend needs.

Payment events

Event	When it is sent	Common action
`payment.completed`	A payment finishes successfully	Mark an order, invoice, or wallet top-up as paid
`payment.failed`	A payment fails or is rejected	Mark the payment attempt as failed and allow retry
`payment.canceled`	The customer canceled the STK prompt	Release holds or allow a new checkout attempt

Payment statuses & outcomes

Map each payment status to webhook events, terminal outcomes, and Daraja result codes.

Customer events

Event	When it is sent	Common action
`customer.created`	A customer record is created	Mirror the customer in your system
`customer.updated`	A customer record changes	Update local customer details
`customer.deleted`	A customer record is deleted	Archive or unlink the local customer

Event payloads

Payment event payloads contain the Moflay payment or transaction data needed to reconcile the event with your system. Customer event payloads contain the affected customer record. Use stable Moflay identifiers such as paymentId, transactionId, and customerId to connect webhook events to your internal records.

Choose events for your integration

Payment-only checkout: subscribe to payment.completed, payment.failed, and payment.canceled when you need to distinguish user cancellation from other failures.
Customer sync: add customer.created, customer.updated, and customer.deleted.
Dashboard-only workflows: you may not need webhooks unless another system must react automatically.