Counterparty transaction webhooks

Counterparty transaction webhooks

Counterparty balances now report every movement over webhooks, matching the GET /api/v1/counterparties/{counterpartyId}/transactions endpoint. Two new topics:

Topic	Fires when
CounterpartyTransactionCreated	A movement first appears on the counterparty's account, usually as Pending
CounterpartyTransactionUpdated	A movement settles (Posted) or is voided before settling (Archived)

Each payload mirrors a row from the transactions list exactly — transactionId, counterpartyId, amount in cents, currency, direction, type, status, description, effectiveAt and postedAt — so you can act on the event without re-reading the list.

Two views of the same money

These topics describe ledger movements. The existing CounterpartyPayout*, CounterpartyTransfer* and CounterpartyIncomingPayment topics describe the operations that cause them.

They overlap deliberately, and nothing about the existing topics has changed. Subscribe to whichever view fits:

• The operation topics carry operation-specific detail — a payout's effectiveDate, a return's returnCode, a transfer's failureReason.
• The transaction topics are complete: every movement that changes a counterparty's balance appears, including ledger corrections and settlements that no operation topic covers.

If you subscribe to both, expect two events for one movement. Deduplicate on the event id in included[0].id.

One event per side of a transfer

A transfer between two of your counterparties fires two events, one per counterparty, each carrying the direction that side experienced — Debit for the source, Credit for the destination.

Pending is not spendable

CounterpartyTransactionCreated usually arrives with status Pending, which counts toward the counterparty's pending balance but not its available balance. Wait for CounterpartyTransactionUpdated with status Posted before treating the funds as available for a payout.