CallbackDesk

CallbackDesk is a CLI-first callback debugger and replay tool for payment integrations.

npx callbackdesk doctor http://localhost:3000/api/mpesa/callback

The command creates a short-lived hosted callback URL, waits for provider callbacks, forwards each callback to your local endpoint, records the local response, and lets you replay the same payload after fixing your handler.

Quick Start

1. Start your local app.
2. Run Doctor with your local callback endpoint.
3. Paste the printed Callback URL into your provider callback setting or sandbox request.
4. Keep the terminal open while callbacks are forwarded to localhost.
5. Open the printed Inbox URL to inspect redacted payloads and delivery attempts.
6. Replay an event after fixing your handler.

callbackdesk replay <event-id>

Commands

callbackdesk doctor <local-callback-url>
callbackdesk replay <event-id>
callbackdesk sample stk-success
callbackdesk sample stk-failed
callbackdesk events
callbackdesk status
callbackdesk evidence
callbackdesk end

Hosted API

The default API is:

https://api.loremipsum.co.ke

Override it when needed:

CALLBACKDESK_API_BASE_URL=https://api.example.com callbackdesk doctor http://localhost:3000/api/mpesa/callback
callbackdesk doctor http://localhost:3000/api/mpesa/callback --api https://api.example.com

Account Mode

Use account mode when you need projects, longer retention, and revocable project CLI tokens. Create the project and token from the CallbackDesk account console, then run:

callbackdesk doctor http://localhost:3000/api/mpesa/callback \
  --project prj_... \
  --token cbds_...

Project tokens are shown once and stored only as hashes.

Security Model

CallbackDesk receives the public provider callback, stores it, and the local CLI forwards it to localhost. The hosted service does not call arbitrary developer localhost URLs directly. Generated callback and inbox URLs contain capability tokens; treat them as sensitive session URLs.