Once money is moving continuously, notification design stops being an afterthought. Webhooks, polling and streaming each solve a different problem, and the right answer usually involves more than one of them. Choosing deliberately saves a great deal of later rework.

Three models, three trade-offs

  • webhooks (push) — low latency, but delivery is at-least-once and ordering is not guaranteed
  • polling (pull) — simple and predictable, but adds latency and load; good for reconciliation
  • streaming — a continuous feed of events, well suited to high-volume consumers that keep state

None is universally correct. The question is what the consumer needs: a prompt alert, a periodic truth check, or a live picture.

Match the model to the task

A retail interface wants a push notification when a payment settles. A reconciliation job wants a pull that compares the ledger with partner statements on a schedule. A treasury dashboard wants a stream it can hold open and update continuously. Because SUPA's ledger records every operation with attribution to principal, agent and policy version, all three models read from the same source of truth. The choice is rarely exclusive. A system may stream into an internal bus for consumers that keep state, expose webhooks for clients that need a ping, and poll on a schedule to confirm nothing was missed.

Design for what breaks

Whichever model you choose, assume events can be missed, duplicated or delivered late. Idempotent handling, explicit status fields and a periodic reconciliation pass close the gaps that real-time delivery inevitably leaves. For high-volume consumers, a stream is often paired with a checkpoint: read the feed for freshness, and keep a periodic reconciliation against the attributed ledger for correctness.

  • deduplicate by event id, regardless of model
  • carry explicit status rather than inferring it
  • reconcile on a schedule as a safety net
  • verify signatures on any pushed event

In short

  • Push is fast but unreliable in ordering; pull is slow but dependable; streaming suits continuous state.
  • Choose per consumer, not per system.
  • All three read the same attributed ledger.
  • Always back real-time delivery with scheduled reconciliation.

See how events and the ledger fit the architecture: developers.