Skip to main content
Endl sends a 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.id is its txn_… id and data.customerId is the owning customer’s cus_… id
  • use the standard envelope, signature and retry rules from the Webhooks guide
Subscribing: use "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.
Go by eventType, not data.status, for failures and refunds. Some rails report a terminal failure or a return on the sub-status while the status itself stays IN_REVIEW. Endl sends transaction.failed or transaction.refunded as soon as either says so, so data.status on those events can read IN_REVIEW.

Typical lifecycle

Things to know:
  • transaction.updated is optional. A fast transfer can settle during submit, so transaction.completed may follow transaction.initiated directly.
  • transaction.updated can repeat, for example once when the funds are confirmed and again when the payout is accepted by the receiving rail. Check subStatus to tell them apart.
  • Holds send nothing. IN_REVIEW (compliance review) and PENDING_TRAVEL_RULE are 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.updated arrived late.

Events in detail

transaction.initiated

When: your Submit transaction call succeeded. Sent once per transaction. What to do: store the txn_ id against your own payment and show it as “processing”. Wait for a final event.

transaction.updated

When: the transaction moved to IN_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 is COMPLETE, 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 that data.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, failed and refunded as final. Ignore any later transaction.updated for the same txn_ 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.