Payout Webhooks

Webhooks let your system react to payout status changes without polling. Set the notifyUrl parameter when creating a payout (Programmatic Payouts), and Confirmo will send an HTTP POST to that URL whenever the payout’s status changes.

When Webhooks Fire

A webhook is sent when the payout is created and on every status change: draft, prepared, pending_verification, confirmed, sending, done, expired, and canceled.

Two important boundaries:

Webhooks fire on primary status changes only. The substatus field rides along in whatever webhook fires anyway — a substatus change by itself (such as compliance_hold appearing on a payout in confirmed) never triggers a webhook. If a payout stays in confirmed unusually long, re-query it via GET /api/v3/payouts/{id}.
Statuses answer “where is it”; substatus answers “why”. Drive your integration logic off status, and use substatus for display and support purposes. See the Payout Lifecycle for the full substatus catalog.

Payload

The webhook body is the same payout object returned by the API — the current state of the payout at the moment the webhook fires:

{
  "id": "WDRnwMw9LIF",
  "createdAt": 1756365304,
  "status": "canceled",
  "substatus": "verification_expired",
  "address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy",
  "amountFrom": 250,
  "amountTo": 0.00234561,
  "currencyFrom": "EUR",
  "currencyTo": "BTC",
  "paymentMethodId": "BITCOIN-BLOCKCHAIN-MAINNET-BTC-CURRENCY",
  "exchangeRate": 106584.21,
  "fee": 1.25,
  "feeCurrency": "EUR",
  "feePaymentMode": "MERCHANT",
  "debitedAmount": 251.25,
  "txid": null,
  "sentAt": null,
  "completedAt": null,
  "reference": "invoice-2026-0812",
  "notifyUrl": "https://yourEShop.com/payoutProcess"
}

Key fields to act on:

Field	Meaning
`status`	The payout’s current lifecycle status. Treat the payout as paid only on `done`.
`substatus`	The reason detail, when one applies. May be `null`. Tolerate unknown values — new ones may be added over time; treat anything you don’t recognize as “no specific reason available”.
`txid`	The blockchain transaction ID, assigned when the payout completes.

Verifying Webhooks

Payout webhooks are signed the same way as other Confirmo v3 webhooks — validate the signature header before trusting the payload. See Callback Password.

Delivery and Retries

If your endpoint doesn’t respond with a 2xx status, Confirmo retries the delivery with an exponential backoff, up to a maximum number of attempts. If deliveries keep failing, you’ll receive a warning email. Because webhooks can arrive delayed or out of order after retries, always confirm the current state with GET /api/v3/payouts/{id} before acting on a stale event.