GET /api/v1/route-intent/:intentId/status until it reaches success or failed. With webhooks, you register one HTTPS URL for your project in the Client Dashboard, and Trustware POSTs a webhook event to it whenever one of your project’s route intents changes in a way you’d act on.
Each webhook event carries the same body /status would return at that moment, inside a small envelope. You don’t need to call Trustware back to find out what changed.
Polling or webhooks
/status keeps working exactly as before, and it stays the source of truth. Webhooks are additive: you can use both, and you should fall back to /status for anything that happened before you registered your URL.
Webhooks go from Trustware’s servers to yours. They don’t replace the widget’s own status tracking. The widget runs in the payer’s browser, which a webhook can’t reach, so it keeps polling as it does today. No SDK change is needed to use webhooks.
When a webhook event fires
A webhook event fires when a route intent:- changes
status: it’s committed (submitted), startsbridging, reachessuccessorfailed, orexpired, including a late commit of an expired route intent - has its source transaction replaced, so
source_tx_hashchanges - has an approve step confirmed on a multi-step route, before the commit
- gets a
dest_tx_hashfor the first time
POST /route doesn’t. Neither do routine updates that only refresh fields such as update_date, poll_attempt or status_raw while a route is in transit. Event types lists each type.
What you need to handle
Delivery is at least once and unordered. Your handler needs to cope with both:- Duplicates. The same webhook event can arrive more than once. The
webhook-idheader is unique per webhook event and stays the same on every retry and redelivery, so use it to drop exact duplicates. - Out of order. Webhook events can arrive in a different order from the one they happened in.
sequencecounts one route intent’s webhook events from 1, going up by exactly 1. If you’ve already processed an equal or highersequencefor that route intent, ignore the webhook event. - Unknown types. Trustware may add new event types. Return
2xxfor any type you don’t recognize, and ignore it.
- Read the raw request body as bytes.
- Verify the signature. Reject the request if it fails.
- Drop it if you’ve already seen its
webhook-id. - Drop it if you’ve already processed a higher or equal
sequencefordata.intent_id. - Record it, return
2xxwithin 15 seconds, and do slow work after responding.
Staging and production
If you run staging and production as separate projects, each has its own webhook URL and secret.Only new changes
A newly registered webhook URL receives webhook events for changes from that moment on. Trustware never sends webhook events for changes made before you registered. For those, use/status.
API versions
Today the only API version isv1. The envelope fields (type, timestamp, apiVersion, sequence, test and data) are camelCase, and data follows the v1 /status body, which is snake_case.
Next steps
Event types
The eight types and when each one fires.
Payload
The envelope, the headers, and example bodies.
Verify signatures
Standard Webhooks v1 signatures, code samples, and a test vector.
Set up in the dashboard
Register a URL, send test events, and read the delivery log.
