Webhooks API

Endpoints

Outbound (delivery logs)

Method	Path	Scope	Description
GET	/v1/webhooks/logs	webhooks:read	List delivery attempts

Inbound (provider callbacks — public)

Method	Path	Description
POST	/v1/webhooks/mpesa	M-Pesa STK callback
POST	/v1/webhooks/stripe	Stripe event callback
POST	/v1/webhooks/paypal	PayPal event callback
POST	/v1/webhooks/mpesa/transactionstatus/result	M-Pesa status query result
POST	/v1/webhooks/mpesa/transactionstatus/timeout	M-Pesa status query timeout
POST	/v1/webhooks/mpesa/reversal/result	M-Pesa reversal result
POST	/v1/webhooks/mpesa/reversal/timeout	M-Pesa reversal timeout

Delivery Logs

GET /v1/webhooks/logs?status=dead&page=1
X-API-Key: sk_live_...

Query Parameters

Param	Type	Description
status	string	Filter: pending, delivered, retrying, dead
event_type	string	Filter: payment.completed, etc.
page	int	Page number (default 1)
page_size	int	Items per page (default 50, max 100)

Response

{
  "success": true,
  "data": [
    {
      "id": "delivery-uuid-...",
      "transaction_id": "txn-uuid-...",
      "event_type": "payment.completed",
      "status": "delivered",
      "attempts": 1,
      "last_status_code": 200,
      "last_error": null,
      "delivered_at": "2025-01-01T12:00:05Z",
      "next_retry_at": null,
      "created_at": "2025-01-01T12:00:00Z"
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 1 }
}

Delivery Lifecycle

stateDiagram-v2
    [*] --> pending: Outbox entry created
    pending --> processing: Worker claims job
    processing --> delivered: 2xx response
    processing --> retrying: Non-2xx / timeout
    retrying --> processing: Retry delay elapsed
    retrying --> dead: 5 attempts exhausted
    dead --> [*]: Manual review
    delivered --> [*]