Webhooks | Stakaba Docs

Stakaba sends a POST request to your server when a payment reaches a final state. This is how you reliably confirm payments — do not rely solely on the customer returning to your page.

Configure your webhook URL

Set your webhook URL when creating a payment in metadata, or configure a global URL in the dashboard under Settings → Webhooks.

Webhook payload

{
  "event": "transaction.success",
  "internalReference": "M_X7Y8Z9W0",
  "status": "SUCCESS",
  "type": "COLLECTION",
  "grossAmount": 5000,
  "stakabaFee": 125,
  "netAmount": 4875,
  "currency": "TZS",
  "mobileNumber": "255742000331",
  "network": "Mpesa",
  "providerReference": "MPESA12345",
  "createdAt": "2026-06-05T14:22:00Z",
  "metadata": {
    "orderId": "ORD-2026-001"
  }
}

Event types

Event	When
`transaction.success`	Payment confirmed and funds received
`transaction.failed`	Payment failed — nothing was charged

Responding to webhooks

Return HTTP 200 to acknowledge receipt. If Stakaba doesn’t get a 200, it retries up to 5 times with exponential backoff.

HTTP/1.1 200 OK

Verify it’s from Stakaba

Check that the internalReference matches one you created and that the amount matches your records. Always verify the transaction status from the API before fulfilling an order:

GET /api/v1/transactions/{internalReference}
x-api-key: sk_live_...

Never fulfil an order based on the webhook alone. Always verify via the API to prevent replay attacks.

Test webhooks

Use your sandbox key to trigger test payments. Stakaba sends webhooks for sandbox transactions to your configured URL, letting you test your handler end-to-end.