A webhook is the moment your system learns that something happened elsewhere. When that something is money movement, the ordinary decisions — retries, ordering, signatures — become consequential. Getting webhooks wrong means gaps in your records that no amount of dashboarding can fix.

Delivery is at-least-once

Assume every webhook may arrive more than once and may arrive out of order. This is not a flaw to eliminate but a reality to design for. The receiving side should treat each event as a fact with an identifier, and store it idempotently: the second delivery of the same event changes nothing.

Ordering and reconciliation

Networks do not guarantee that event two arrives after event one. If your logic depends on sequence, do not infer it from arrival time. Carry an explicit status in each event and reconcile periodically against the source, rather than trying to reconstruct order from a stream of notifications.

  • accept that duplicates happen; deduplicate by event id
  • never infer ordering from timestamps alone
  • reconcile against the ledger on a schedule, not only in real time

Signature verification

An unsigned webhook is a claim, not a fact. Events should be signed, and the receiver should verify the signature before acting. SUPA's documents are signed and verifiable for the same reason: the value of a notification depends on being able to establish that it came from the counterparty it names.

Where events drive downstream systems — balances, limits and reporting — the same discipline applies as in the ledger itself: append rather than overwrite, and let the sequence of verified events define the current state. An event that cannot be verified is a prompt to reconcile, not a reason to update a balance on trust.

A practical checklist

  • verify signatures before processing
  • record events idempotently
  • carry explicit status, never infer it
  • reconcile against the double-entry ledger periodically
  • alert on missing events rather than waiting for a user to notice

In short

  • Plan for at-least-once delivery and out-of-order arrival.
  • Deduplicate by event id; the same event must not count twice.
  • Verify signatures — an unsigned event is only a claim.
  • Close every gap by reconciling against the ledger.

Design your integration from the developer corner: developers.