Track cross-chain transactions with webhooks and polling
A cross-chain transaction can keep moving after a user closes the browser. Your backend still needs to know whether the transfer completed, failed or needs attention.
Trustware webhooks send signed route-intent updates to your server. Polling requests the current state from /status. You can use both: webhooks for backend notifications, and /status for reconciliation and changes that happened before you registered your webhook URL.
When to use each
| Requirement | Use |
|---|---|
| Keep backend records updated as route intents change | Webhooks |
| Read the current state of a particular route intent | /status |
| Check changes from before webhook registration | /status |
| Keep the prebuilt widget updated in the user's browser | Its existing polling behavior |
Webhooks do not replace the widget's tracking. They run between servers, and no SDK change is required to use them. The webhook overview explains how they work alongside the status API.
What a webhook tells your backend
Events cover route-intent status changes and specific transaction updates, including a replaced source transaction or the first appearance of a destination transaction hash. Building a route alone does not emit a webhook event.
Each event contains a type, a per-intent sequence, and data holding the status payload at the time of the change. That payload is a snapshot, not a guarantee that nothing has changed since delivery began.
Use the event types reference to decide which updates your application needs. Do not assume every route follows the same event sequence. An expired intent can also resume if its transaction is committed late.
Verify before processing
Register a public HTTPS endpoint for your project in the Client Dashboard. Store the signing secret on your server, never in browser code.
Verify each delivery against its raw request body before acting on it. Parsing and re-serializing JSON can change the bytes and break signature verification. Trustware uses Standard Webhooks signatures; the signature verification guide provides library examples and timestamp checks.
Dashboard test events reach your real handler with test: true. Recognize them without crediting funds or triggering production business actions. Follow the dashboard setup guide for registration and testing.
Handle duplicates and out-of-order updates
Delivery is at least once and unordered. Events can also arrive concurrently.
Use webhook-id to identify repeated delivery of the same event. Use sequence within each route intent to prevent an older snapshot from overwriting newer state. Make those checks safe under concurrent requests, rather than assuming deliveries arrive one at a time.
For state updates, inspect data.status as well as the event type. For example, an event announcing a destination transaction can carry a successful status snapshot. If a newer snapshot has already been applied, a delayed event should not roll the application back.
Keep downstream actions idempotent too. Receiving an event again should not issue a second credit or repeat a payout. Acknowledge valid but unrecognized event types with 2xx and ignore them, as the event reference recommends.
Record the event, then acknowledge it
Return 2xx within 15 seconds. If processing takes longer, durably record or enqueue the verified event before acknowledging it, then do the slower work asynchronously. Acknowledging an event that exists only in memory can lose work if the process stops.
Failed deliveries are retried under the documented schedule. A 410 Gone response disables the project's webhook URL, so do not use it to reject an event you simply do not need. See delivery and retries for response handling and recovery limits.
Recover without assuming historical replay
Webhooks cover changes made after URL registration. They do not backfill changes from before registration; use /status for those.
If delivery is disabled, re-enabling it resumes new deliveries but does not automatically send the accumulated backlog. The dashboard can redeliver eligible recorded events within its 30-day retention window. Redelivery keeps the same event ID and sequence, so the same duplicate and ordering rules apply.
Use /status when you need the current route state during reconciliation. A webhook delivery log and your application's completed business actions are separate records.
Verify the outcome your application promised
A signed event proves the message passed verification. It does not, by itself, prove that a vault credited the expected shares or that your application completed its accounting.
When a route includes a destination action, verify the intended contract outcome before recognizing credit. Follow the cross-chain vault verification guide for the distinction between route completion and a credited deposit.
Start with webhook setup, and keep the status API available for reconciliation.