Inbound webhooks

When you pass webhookUrl on POST /v1/collect or POST /v1/disburse, SwarmByte queues an HTTP POST to that URL with a JSON body for lifecycle updates. These requests are not cryptographically signed — rely on HTTPS, a hard-to-guess path if you can, and idempotent processing keyed by transactionId (and status), not only by event name. Do not expect a static callback secret or HMAC header.

Event names

The event string identifies the stage (for example collection.initiated, collection.success, collection.failed, and the analogous disbursement.* values). You may also see transaction.updated. Always apply state changes from transactionId, type, and status — not only from the event name — so your integration stays correct if new event labels are added.

Headers your server receives

Content-Type: application/json
X-Swarmbyte-Timestamp — ISO 8601 timestamp for when the request was built.
User-Agent: SwarmByte-Webhooks/1.0

There is no X-Swarmbyte-Signature (or similar) verification header. Poll GET /v1/collect/transactions/:id or GET /v1/disburse/transactions/:id when you need to reconcile or verify after a network issue.

Body (example — successful collection)

{
  "event": "collection.success",
  "transactionId": "COL_d77d719fb8a02101",
  "status": "SUCCESS",
  "type": "COLLECTION",
  "amount": 50000,
  "fee": 1500,
  "netAmount": 48500,
  "msisdn": "256701234567",
  "timestamp": "2026-04-28T10:40:00.000Z"
}

Body (example — successful disbursement)

{
  "event": "disbursement.success",
  "transactionId": "DIS_820d0146bb94ae4d",
  "status": "SUCCESS",
  "type": "DISBURSEMENT",
  "amount": 100000,
  "fee": 3000,
  "netAmount": 100000,
  "msisdn": "256772123456",
  "timestamp": "2026-04-28T10:40:00.000Z"
}

For disbursements, netAmount equals amount (recipient received the full payout; fee was charged on top from your wallet). Field-by-field reference: see Field reference → Inbound webhooks.

Your response

Return any 2xx status to acknowledge delivery; non-2xx can cause retries. Design your handler to be safe under duplicate delivery and out-of-order webhooks.