transaction.* webhook when you submit a transaction and each time it
reaches a status you need to act on. Payouts, onramps, offramps and
stablecoin-to-stablecoin transfers all use this one family; there are no
payout.* events.
All five events:
- relate to one transaction, so
data.idis itstxn_…id anddata.customerIdis the owning customer’scus_…id - use the standard envelope, signature and retry rules from the Webhooks guide
"eventFilter": ["transaction.*"] to receive all of them.
Payload fields
Standard rendering rules apply: every leaf value is a string, null fields are left
out, keys are sorted, and new fields can appear without a version change. Amounts,
fees and the FX rate are not in the payload — read them from Get transaction.
Typical lifecycle
transaction.updatedis optional. A fast transfer can settle during submit, sotransaction.completedmay followtransaction.initiateddirectly.transaction.updatedcan repeat, for example once when the funds are confirmed and again when the payout is accepted by the receiving rail. ChecksubStatusto tell them apart.- Holds send nothing.
IN_REVIEW(compliance review) andPENDING_TRAVEL_RULEare internal holds and emit no event. If a transfer goes quiet, poll Get transaction. - POBO transactions don’t emit these events. Transactions submitted through the POBO endpoints are tracked through those endpoints instead.
- Order isn’t guaranteed across retries. Never move a transaction back from a
final state because an older
transaction.updatedarrived late.
Events in detail
transaction.initiated
When: your Submit transaction call succeeded. Sent once per transaction. What to do: store thetxn_ id against your own payment and show it as
“processing”. Wait for a final event.
transaction.updated
When: the transaction moved toIN_PROGRESS — funds confirmed and the transfer
under way, or a bank payout accepted by the receiving rail.
What to do: nothing is required. Update your own status if you show progress.
transaction.completed
When: the transfer settled. The status isCOMPLETE, and it’s final.
What to do: mark the payment as paid. Call Get transaction if you need the final
amounts or fees.
transaction.failed
When: the transfer was rejected or cancelled and will not settle — by compliance, by Endl, or by the receiving rail. Final. What to do: mark the payment as failed and call Get transaction for the reason. To try again, generate a new quote and submit a new transaction.transaction.refunded
When: the funds were returned to the source, for example because the recipient’s bank returned the payment. Final. What to do: mark the payment as refunded and reconcile the returned funds. Note thatdata.status can read IN_REVIEW here — see the warning above.
Best practices
- Verify the signature, then deduplicate on
eventId, then act. Delivery is at least once, so the same event can arrive twice. - Treat
completed,failedandrefundedas final. Ignore any latertransaction.updatedfor the sametxn_id. - Use the API as the source of truth. Webhooks tell you that something changed; Get transaction tells you the full state, including amounts and fees.
- Subscribe with
transaction.*so you automatically receive new transaction events Endl adds later.