Get Notifications
Optional endpoints — receive intent status updates and effect signals
Beyond the core credit and debit interface, your bridge can receive notifications about intent progress and ledger events. These endpoints are optional — enable them by declaring the corresponding traits in your bridge registration.
For proof submission — how your bridge reports results back to the ledger — see Build the Credit and Debit Interface.
Intent status notifications
To receive notifications when an intent reaches a final state (completed or rejected), register an effect that filters on intent status changes. The effect delivers the event to your bridge or to any webhook URL — you choose the delivery mechanism when configuring the effect.
If your bridge declares the events trait, effects can deliver intent status events through the same POST /v2/effects/:handle endpoint described below. Alternatively, configure a webhook action to deliver notifications to any URL your system exposes.
This approach uses the same effects system that handles balance changes and other ledger events, keeping the bridge's core interface focused on the two-phase commit protocol. Use these notifications to trigger downstream callbacks — notify payment initiators, update UI status, send push notifications, or log the final outcome.
Effect filtering and registration is covered in the Connecting Systems advanced guides. Filters let you target specific intent schemas, wallet patterns, or status values — so you only receive the notifications you need.
Effect signals
Trait: events
POST /v2/effects/:handle
When a registered effect with a bridge action triggers, the ledger delivers the event to your bridge. The handle in the URL is the effect's handle, not the intent handle. The body contains the event that triggered the effect — typically a balance change, record creation, or status transition.
Effects are useful for reacting to ledger events outside the credit/debit flow: balance thresholds, settlement completions, or custom business events.
Effect filtering is configured on the effect record itself, not on the bridge. Effect registration is covered in the Connecting Systems advanced guides.
Build the Credit and Debit Interface
The core endpoints every bridge must implement.
Handle Errors and Retries
Retry mechanics, idempotency, and the commit-never-fails contract.