Payout webhooks and status events

The API call is the beginning, not the end

When you create a payout, the response tells you the instruction was accepted, not that money arrived.

Create payout
      |
Accepted
Status: processing

... time passes ...

Status: completed

Between those two moments the payment travels a rail, a bank accepts or rejects it, and on some rails a return can arrive days later. Your system needs a way to hear about each change.

Option 1: Polling

The simplest approach: ask again until the answer changes.

Your system          Payout API
    |                     |
    |---- status? ------->|
    |<--- processing -----|
    |                     |
    |---- status? ------->|
    |<--- processing -----|
    |                     |
    |---- status? ------->|
    |<--- completed ------|

Polling is easy to build and easy to reason about. Its costs are lag (you learn the news on your schedule, not when it happens) and wasted requests, which grow with volume.

Option 2: Webhooks

A webhook inverts the arrow: the payout system calls you when something changes.

Payout API                Your system
    |                          |
    |-- event: completed ----->|
    |<-------- 200 OK ---------|

You get the news when it happens, with no polling loop. In exchange, you take on delivery mechanics: your endpoint has to be reachable, fast, and correct about what it acknowledges.

Deliveries retry, so handlers must expect duplicates

A webhook delivery can fail: your server was deploying, a timeout hit, a load balancer hiccuped. Senders handle this by retrying, which means the same event can arrive more than once.

Delivery 1: event abc123
No acknowledgment
      |
Delivery 2: event abc123
Acknowledged

Handled: once

The fix is the same idea as duplicate payout protection: track event identifiers, and make handling the same event twice change nothing the second time.

Events can arrive out of order

Two events about one payout can reach you in the wrong sequence, especially around retries.

Sent:      processing -> completed
Received:  completed  -> processing

A handler that blindly applies the last event received would mark a completed payout as processing. Safer patterns: treat events as hints and fetch the current status before applying, or ignore any event older than the state you already hold.

Belt and suspenders

Mature payout integrations use both channels: webhooks for freshness, and a periodic reconciling poll that catches anything a missed delivery left behind.

Webhooks   -> fast news, usually complete
Poll sweep -> slow news, always complete
      |
Your records match reality

Where DiscoFi fits

Every DiscoFi payout carries a status you can query at any time, status changes stream into the dashboard live as the rail settles each payment, and programs can receive webhooks as statuses change. The reconciling sweep comes free: the same ledger that records each payout is the record your poll would check.