# 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)

```json
{
  "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)

```json
{
  "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](https://docs.swarmbyte.com/field-reference.md) → 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.

Source: https://docs.swarmbyte.com/webhooks