Docs / API reference

Webhook endpoints

Tell Pitisha where to send events, and look back at what was sent.

The Webhook endpoint object

An HTTPS URL on your server that receives signed events. See the Webhooks guide for the signature scheme.

Attributes

idstring
Unique identifier, starting we_.
urlstring
Your HTTPS endpoint.
eventsstring[]
Which event types to send.
statusstring
Whether events are being sent.
One of enabled, disabled
secret_last4string
The last four characters of the signing secret. The full secret is shown once when you create the endpoint.

Example object

{
  "id": "we_71c2xk",
  "object": "webhook_endpoint",
  "url": "https://api.example.com/pitisha/webhooks",
  "events": [
    "collection.recorded",
    "collection.failed",
    "payout.sent",
    "settlement.landed"
  ],
  "status": "enabled",
  "secret_last4": "71c2",
  "livemode": false,
  "created_at": "2026-06-12T10:00:00+03:00"
}

POST/v1/webhook_endpoints

Create a webhook endpoint

Start receiving events.

The response includes a secret field with the full signing secret. It is shown once. Store it on your server.

Body parameters

urlstringrequired
An HTTPS URL.
eventsstring[]
Event types to send. Defaults to all.

Errors

400 invalid_request
403 permission_denied

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/webhook_endpoints" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/pitisha/webhooks",
    "events": [
      "collection.recorded",
      "collection.failed"
    ]
  }'

{
  "id": "we_71c2xk",
  "object": "webhook_endpoint",
  "url": "https://api.example.com/pitisha/webhooks",
  "events": [
    "collection.recorded",
    "collection.failed",
    "payout.sent",
    "settlement.landed"
  ],
  "status": "enabled",
  "secret_last4": "71c2",
  "livemode": false,
  "created_at": "2026-06-12T10:00:00+03:00",
  "secret": "whsec_REPLACE_WITH_REAL_SECRET"
}

GET/v1/webhook_endpoints

List webhook endpoints

All endpoints in this mode.

Query parameters

limitinteger
How many items to return, from 1 to 100. Defaults to 20.
starting_afterstring
A cursor from a previous response's next_cursor. Returns the next page.

Errors

401 authentication_failed

See Errors for what each means.

curl -X GET "$PITISHA_API/v1/webhook_endpoints" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "we_71c2xk",
      "object": "webhook_endpoint",
      "url": "https://api.example.com/pitisha/webhooks",
      "events": [
        "collection.recorded",
        "collection.failed",
        "payout.sent",
        "settlement.landed"
      ],
      "status": "enabled",
      "secret_last4": "71c2",
      "livemode": false,
      "created_at": "2026-06-12T10:00:00+03:00"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_9fK2mQ"
}

DELETE/v1/webhook_endpoints/{id}

Delete a webhook endpoint

Stop sending to it.

Path parameters

idstringrequired
The endpoint id.

Errors

404 not_found

See Errors for what each means.

curl -X DELETE "$PITISHA_API/v1/webhook_endpoints/ID_FROM_RESPONSE" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "id": "we_71c2xk",
  "object": "webhook_endpoint",
  "deleted": true
}

GET/v1/events

List events

Everything Pitisha has sent you.

Query parameters

typestring
Filter by event type.
limitinteger
How many items to return, from 1 to 100. Defaults to 20.
starting_afterstring
A cursor from a previous response's next_cursor. Returns the next page.

Errors

401 authentication_failed

See Errors for what each means.

curl -X GET "$PITISHA_API/v1/events" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "evt_6h2p0q",
      "object": "event",
      "type": "collection.recorded",
      "created_at": "2026-10-28T11:20:04+03:00",
      "livemode": false,
      "data": {
        "object": {
          "id": "col_8f3k2q",
          "object": "collection",
          "status": "succeeded",
          "amount": 250000,
          "currency": "KES",
          "source": "paybill",
          "reference": "INV-204117",
          "description": "Order 1042",
          "customer": {
            "phone": "+254712000000"
          },
          "wallet_id": "wal_main",
          "shortcode_id": "sc_4012345",
          "match": {
            "state": "matched",
            "sale_id": "sale_1042"
          },
          "routing": {
            "gateway": "daraja",
            "attempts": 2,
            "failed_over": true
          },
          "failure": null,
          "metadata": {
            "order_id": "1042"
          },
          "livemode": false,
          "created_at": "2026-10-28T11:20:04+03:00"
        }
      }
    }
  ],
  "has_more": true,
  "next_cursor": "cur_9fK2mQ"
}

POST/v1/events/{id}/redeliver

Redeliver an event

Send an event to your endpoint again.

Useful after you fix an outage on your side. The same event id is sent, so make your handler idempotent.

Path parameters

idstringrequired
The event id.

Errors

404 not_found

See Errors for what each means.

curl -X POST "$PITISHA_API/v1/events/ID_FROM_RESPONSE/redeliver" \
  -H "Authorization: Bearer $PITISHA_SECRET_KEY"

{
  "id": "evt_6h2p0q",
  "object": "event",
  "type": "collection.recorded",
  "created_at": "2026-10-28T11:20:04+03:00",
  "livemode": false,
  "data": {
    "object": {
      "id": "col_8f3k2q",
      "object": "collection",
      "status": "succeeded",
      "amount": 250000,
      "currency": "KES",
      "source": "paybill",
      "reference": "INV-204117",
      "description": "Order 1042",
      "customer": {
        "phone": "+254712000000"
      },
      "wallet_id": "wal_main",
      "shortcode_id": "sc_4012345",
      "match": {
        "state": "matched",
        "sale_id": "sale_1042"
      },
      "routing": {
        "gateway": "daraja",
        "attempts": 2,
        "failed_over": true
      },
      "failure": null,
      "metadata": {
        "order_id": "1042"
      },
      "livemode": false,
      "created_at": "2026-10-28T11:20:04+03:00"
    }
  }
}