Skip to main content
The wallet.transaction.* events report what happened to a transaction Dynamic sent on a user’s behalf, including the ones that never land. Subscribe to them to tell a failed payment apart from one still in flight, without polling. Available today for gas-sponsored EVM transactions.

​
The five events

reverted and failed are separate because they call for different things. A revert means the transaction reached the chain and the contract refused it, so the call or the account state needs to change. A failure means it never got there at all.

​
What to rely on

  • Exactly one final event per transaction. completed, reverted and failed are mutually exclusive.
  • The others are best-effort. A transaction that resolves quickly may skip broadcasting or confirming, so do not wait for them.
  • Order is not guaranteed. Branch on the status in the payload, not on the order events arrive.
  • Delivery is at-least-once. Deduplicate on the event id.
  • The transaction id is stable across every event for one transaction, and matches the request id the sponsorship call returned.
  • Fields with nothing to report are left out rather than sent as null, so check whether a field is present.
Each event carries the transaction id, its status, the wallet address, the chain, and when it was requested. Once the transaction reaches the chain it also carries the transaction hash and block explorer links, and a sponsored transaction carries the sponsoring address and the fees. The two failure events add a reason and a message. For the shared event envelope and endpoint setup, see Setting up webhooks.

​
Failure reasons

The reason is a fixed code. The message beside it is human-readable, useful in a log or a support ticket, but not something to branch on. A transaction rejected before reaching the chain arrives as failed, with the reason explaining why. So failed with CONTRACT_REVERTED means the call would have reverted and was never sent. Treat the list as open. New codes can appear, so route anything unrecognised the same way you route UNKNOWN.

​
Alongside on-chain activity

These events are independent of wallet.activity, and answer a different question. Where both are enabled and the wallet is registered for monitoring, a sponsored transfer that moves funds fires both, in no guaranteed order. Neither replaces the other, and neither guarantees the other will arrive. If you already handle wallet.activity and only want to learn about failures, subscribe to wallet.transaction.reverted and wallet.transaction.failed alone.

​
Getting started

  1. Set up a webhook endpoint
  2. Subscribe to the transaction events you want
  3. Branch on the status, and deduplicate on the event id
Last modified on September 25, 2026