Receive journeys by webhook
Receive new, changed and unassigned journeys on your webhook endpoint.
You will receive a newly assigned journey on your webhook endpoint and load its full details into your planning. You need an API key and an HTTPS endpoint that verifies the signature as described in Webhooks. Set your webhook URL in Workspace › Webhooks; Transferz then sends your journeys and their changes to your system.
The events you receive
Transfer companies receive these events. Each is a JSON object with one property named after the event.
| Event | When | What you do |
|---|---|---|
journeyFleetAssignedEvent | A journey was assigned to your fleet: by direct assignment, by Transferz by hand, after you accepted an offer, or when it was moved to you from another company. | Add it to your planning. |
journeyFleetUnassignedEvent | A journey was taken away from your company. | Remove it; stop sending updates. |
journeyStatusChangedEvent | The status of one of your journeys changed, including cancellations. | Update the status. |
journeyExecutionDetailsUpdatedEvent | The pickup time, pickup location or drop-off location changed. | Re-plan. |
journeyTravellerInfoUpdatedEvent | Traveller details changed. | Update the details. |
offerCreatedEvent | A new offer (offer flow only). | See Accept or decline offers. |
offerStatusChangedEvent | An offer's status changed (offer flow only). | Update or drop the offer. |
Changes and cancellations are covered in Handle changes and cancellations.
Step 2: Receive the assignment event
When a journey is assigned to you, Transferz posts an event like this:
{ "journeyFleetAssignedEvent": { "created": "2026-11-20T10:47:12.913", "journeyId": 488213, "transferCompanyId": 2290, "journey": { "id": 488213, "code": "TZ7K4Q-1", "pickUp": { "resolvedAddress": "Amsterdam Airport Schiphol (AMS), Evert van de Beekstraat 202, 1118 CP Schiphol, Netherlands", "latitude": 52.3105, "longitude": 4.7683, "hub": true, "iataCode": "AMS" }, "dropOff": { "resolvedAddress": "Herengracht 182, 1016 BR Amsterdam, Netherlands", "latitude": 52.3738, "longitude": 4.8862, "hub": false }, "pickUpTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" }, "vehicleCategory": "SEDAN", "addonsPerQuantity": [{ "type": "MEET_GREET", "amount": 1 }], "travellerInfo": { "firstName": "Alex", "lastName": "Traveller", "passengerCount": 2, "luggageCount": 2, "flightNumber": "TZ1234" } } }}The example is shortened; the event reference lists every field.
Read the journey id from journey.id. The top-level journeyId holds the same value but is
deprecated.
Step 3: Acknowledge it
Verify the signature, store the event, and answer 2xx (for example 204) within 20 seconds. Do the
rest of the work after you have answered. Any other answer, or no answer, counts as a failed delivery
and the event is retried later; see Webhooks.
Step 4: Fetch the full journey
The event leaves out some details, such as the meeting point and the driver. Fetch the journey with the id from the event:
/journeys/488213Referencecurl --request GET \ --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213' \ --header 'Accept: application/json' \ --header 'X-API-Key: YOUR_STAGING_API_KEY'{ "id": 488213, "code": "TZ7K4Q-1", "pickup": { "resolvedAddress": "Amsterdam Airport Schiphol (AMS), Evert van de Beekstraat 202, 1118 CP Schiphol, Netherlands", "latitude": 52.3105, "longitude": 4.7683, "hub": true, "iataCode": "AMS" }, "dropoff": { "resolvedAddress": "Herengracht 182, 1016 BR Amsterdam, Netherlands", "latitude": 52.3738, "longitude": 4.8862, "hub": false }, "pickupTime": { "localTime": "2026-12-01T14:30:00", "timeZone": "Europe/Amsterdam" }, "addonsPerQuantity": [{ "type": "MEET_GREET", "amount": 1 }], "vehicleCategory": "SEDAN", "type": "HUB", "status": "CONFIRMED", "meetingPoint": { "id": 2561, "title": "Schiphol Plaza meeting point", "description": "Walk to the Meeting Point sign in Schiphol Plaza, opposite arrivals 3.", "latitude": 52.3094, "longitude": 4.7622, "type": "HUB" }, "driverCode": "482KQM731", "assignmentStatus": "ASSIGNED", "travellerInfo": { "firstName": "Alex", "lastName": "Traveller", "email": "alex.traveller@example.com", "phone": "+447700900123", "meetAndGreetSignText": "Alex Traveller", "passengerCount": 2, "luggageCount": 2, "flightNumber": "TZ1234", "language": "en" }, "partnerReference": "ORDER-10023", "driver": null, "vehicle": null}The response is shortened; Look up and search journeys explains the fields. The pickup time is the local time at the pickup location; do not convert it.
Next: assign a driver and a vehicle.
Errors
| Problem | Cause | What to do |
|---|---|---|
| No events arrive | No webhook URL saved, or webhooks are switched off for your company | Check the URL in the workspace and send a test event from there. |
| Signature check fails for every event | The body was parsed and re-serialised, or the key was decoded | Verify over the raw bytes; see Webhooks. |
| Events for one journey stop | An earlier event for that journey keeps failing | Events per journey are delivered in order; fix the failing delivery and the rest follow. |
| The same event arrives twice | A retry after a slow or failed answer | De-duplicate on event type, journeyId and created; see Webhooks. |
403 on Get a journey | The journey is not, or no longer, assigned to your company, or the id does not exist | Check the id. If you received journeyFleetUnassignedEvent, the journey is no longer yours. |
401 on Get a journey | The API key is missing, wrong or expired | See Authentication. |
If events were given up after the last attempt, catch up with
Search journeys and the updatedAfter filter; see
Look up and search journeys.
Related
Endpoints
Walk-through