When something happens in your account, TripWorks sends one HTTP POST with a JSON body to every URL you set for that event. This page explains exactly what that request looks like and what your server needs to do, so you can build a receiver that doesn't lose events.
In this article
For failures and retries, see Webhook retries and failed deliveries.
What TripWorks sends
- One request per event, per endpoint. If you list two URLs for an event, each gets its own request. A failure at one doesn't resend the event to the other.
- A few seconds after the action. Delivery starts about five seconds after the event, which gives totals and assignments time to settle.
- One event per action. If a single action touches the same record more than once, you get one webhook for it, not several.
-
A JSON body with
Content-Type: application/json. See Webhook events and example payloads for the shape of each event.
Headers on every request
-
Idempotency-Key: a unique ID for this event and endpoint. It stays the same on every retry of that event. -
X-TripWorks-Delivery-UUID: the same unique ID, under a TripWorks-specific name. -
X-TripWorks-Delivery-Attempt:1on the first try,2on the first retry, and so on.
The Idempotency-Key is the most reliable way to avoid processing an event twice. Save it when you handle an event, and if it shows up again, answer success and skip the work.
What your server must answer
- Any 2xx status means success. 200, 201, 202, and 204 all count as delivered.
- Answer within 15 seconds. A slower response is treated as a failure. Return quickly and do the heavy work in the background.
-
Redirects are followed, up to three. Each hop is checked again for safety. A redirect that drops from
httpstohttp, or that points to a private address, is refused. - Your response body is ignored. Only the status code matters.
What happens when it doesn't succeed
A failure doesn't always mean a retry. Some answers make TripWorks try again, and others stop right away. The rules are on Webhook retries and failed deliveries.
Ordering and duplicates
- Order isn't guaranteed. If an earlier event fails and is retried, it can arrive after a later one. Use the record's own timestamps and IDs, not arrival order, to decide which is newest.
-
Duplicates can happen. If your server handles an event but the reply is lost, the retry sends it again. Deduplicate with the
Idempotency-Key.
Examples
-
Find out if a delivery was a retry: read
X-TripWorks-Delivery-Attempt. Anything above1is a repeat of an event you may have seen. -
Avoid double-charging a guest in your system: store the
Idempotency-Keywith each payment you record, and skip any event whose key you already have. - Keep a slow CRM from timing out: have your endpoint save the JSON to a queue, return 200 at once, and let a worker call the CRM.
- Fix a 404 at your endpoint: check the URL on the setup screen for typos, because a 404 stops delivery for that event without a retry.
Frequently asked questions
Does TripWorks wait for my server to finish its work?
It waits up to 15 seconds for a status code. Return a 2xx quickly and process the data afterward.
Is 201 or 202 accepted, or only 200?
Any status from 200 to 299 counts as success.
Can I tell which delivery a request belongs to?
Yes. The Idempotency-Key and X-TripWorks-Delivery-UUID headers carry the same unique ID for that event and endpoint.
How do I avoid processing an event twice?
Use the Idempotency-Key header. Save it when you process an event, and if the same key arrives again, answer with a 2xx and skip the work. This works no matter why the event arrived twice, so you don't need to track retries yourself.
Why did I get the same event twice?
The first reply may have been lost or slow, so the event was sent again. The same Idempotency-Key comes with every send of an event, so save the key when you handle one and skip any event whose key you've already processed.
Why did events arrive out of order?
Retries can land after newer events. Don't rely on arrival order. Compare timestamps or use the record's current state.
What if my endpoint is on a private network?
TripWorks won't send to private or internal addresses. See Secure your webhook endpoint.
Related
Built for attractions, tours & activities
Wire TripWorks into everything else
See how attractions, tours, and activities push bookings, payments, and waivers into their own systems in real time on TripWorks. Book a demo and make the switch.