Webhook events

Every payout event, its payload, and when it fires. Register for these with the Webhooks API.

These are the events Caibo delivers to your registered webhook endpoints. Each delivery is a POST whose body is a JSON payout event, signed with Caibo-Signature and tagged with a Caibo-Event header. See the Webhooks guide for verification, retries, and idempotency.

Payload shape

All events share the same shape. tx_hash is present only once the payout is completed.

Field	Type	Description
`event`	string	The event name, e.g. `payout.completed`.
`object`	string	Always `"payout"`.
`id`	string	The payout id.
`status`	string	The payout status at the time of the event.
`amount`	string	Decimal amount.
`currency`	string	Asset, e.g. `USDC`.
`mode`	string	`test` or `live`.
`destination`	object	`{ network, address }`.
`tx_hash`	string	Present on `payout.completed`.
`created_at`	string	ISO 8601 UTC.

`payout.created`

Fires when a payout has been created and accepted. Its status is pending.

json

{
  "event": "payout.created",
  "object": "payout",
  "id": "po_9f8e7d6c5b4a",
  "status": "pending",
  "amount": "25.00",
  "currency": "USDC",
  "mode": "live",
  "destination": { "network": "polygon", "address": "0x1234...5678" },
  "created_at": "2026-07-23T14:03:00Z"
}

`payout.processing`

Fires when the payout is being signed and broadcast on-chain. Status is processing.

json

{
  "event": "payout.processing",
  "object": "payout",
  "id": "po_9f8e7d6c5b4a",
  "status": "processing",
  "amount": "25.00",
  "currency": "USDC",
  "mode": "live",
  "destination": { "network": "polygon", "address": "0x1234...5678" },
  "created_at": "2026-07-23T14:03:00Z"
}

`payout.completed`

Fires when the payout has settled on-chain. Status is completed and tx_hash is set. This is the definitive "the money has left" signal.

json

{
  "event": "payout.completed",
  "object": "payout",
  "id": "po_9f8e7d6c5b4a",
  "status": "completed",
  "amount": "25.00",
  "currency": "USDC",
  "mode": "live",
  "destination": { "network": "polygon", "address": "0x1234...5678" },
  "tx_hash": "0x8f3a9c2b1d4e5f60...",
  "created_at": "2026-07-23T14:03:00Z"
}

`payout.failed`

Fires when the on-chain broadcast failed. Status is failed and the amount has been refunded to your balance. Failures are typically transient; you may create a new payout (with a new idempotency key).

json

{
  "event": "payout.failed",
  "object": "payout",
  "id": "po_9f8e7d6c5b4a",
  "status": "failed",
  "amount": "25.00",
  "currency": "USDC",
  "mode": "live",
  "destination": { "network": "polygon", "address": "0x1234...5678" },
  "created_at": "2026-07-23T14:03:00Z"
}

`payout.blocked`

Fires when screening blocked the destination. Status is blocked and no funds moved. Route these to your compliance process — retrying the same destination will block again. See Compliance & screening.

json

{
  "event": "payout.blocked",
  "object": "payout",
  "id": "po_9f8e7d6c5b4a",
  "status": "blocked",
  "amount": "25.00",
  "currency": "USDC",
  "mode": "live",
  "destination": { "network": "polygon", "address": "0x1234...5678" },
  "created_at": "2026-07-23T14:03:00Z"
}

The webhook payload is a snapshot. For anything critical, re-fetch the payout with GET /v1/payouts/{id} to confirm its current state (including the safe screening summary on a blocked payout).