Skip to main content
Moflay webhooks notify your backend when payment and customer events happen. Use webhooks in production instead of relying only on polling.

​
How webhooks fit into the payment flow

1

Your backend creates a payment

Your app calls POST /v1/express with a sandbox or production API key.
2

Moflay processes the M-Pesa result

Moflay receives the Safaricom callback, updates the payment and transaction, and stores the final status.
3

Moflay sends your webhook

Moflay sends a signed event such as payment.completed, payment.failed, or payment.canceled to your configured endpoint.
4

Your backend verifies and handles the event

Your app verifies the signature, checks idempotency, and updates your internal order or customer state.

​
Configure a webhook endpoint

  1. Open Webhooks.
  2. Create an endpoint for your backend URL.
  3. Subscribe to the events your app needs.
  4. Store the signing secret in your backend environment variables.
  5. Verify every incoming webhook before processing the payload.
For most payment integrations, subscribe to:
  • payment.completed
  • payment.failed
  • payment.canceled (when you need to detect the customer dismissing the STK prompt)
Customer events are useful when your backend needs to mirror Moflay customer records.

​
Safaricom callbacks vs Moflay webhooks

Daraja callbacks finalize the M-Pesa result inside Moflay. Your backend consumes Moflay webhooks so it can react to clean, signed payment and customer events. See Daraja callbacks for details on the Safaricom-to-Moflay step.