Skip to content

Receive journeys by webhook

Receive new, changed and unassigned journeys on your webhook endpoint.

Updated · 3 min read

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.

EventWhenWhat you do
journeyFleetAssignedEventA 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.
journeyFleetUnassignedEventA journey was taken away from your company.Remove it; stop sending updates.
journeyStatusChangedEventThe status of one of your journeys changed, including cancellations.Update the status.
journeyExecutionDetailsUpdatedEventThe pickup time, pickup location or drop-off location changed.Re-plan.
journeyTravellerInfoUpdatedEventTraveller details changed.Update the details.
offerCreatedEventA new offer (offer flow only).See Accept or decline offers.
offerStatusChangedEventAn offer's status changed (offer flow only).Update or drop the offer.

Changes and cancellations are covered in Handle changes and cancellations.

Step 1: Register your endpoint

In the workspace, save your staging webhook URL and copy the signing key. The URL must use HTTPS. Implement the signature check from Webhooks before anything else: an event whose signature does not match must be answered with 401 and not processed.

Step 2: Receive the assignment event

When a journey is assigned to you, Transferz posts an event like this:

JSON
{  "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:

GET/journeys/488213Reference
Sign in to fill in your staging key. Sign in
curl --request GET \  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213' \  --header 'Accept: application/json' \  --header 'X-API-Key: YOUR_STAGING_API_KEY'
Response 200
{  "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

ProblemCauseWhat to do
No events arriveNo webhook URL saved, or webhooks are switched off for your companyCheck the URL in the workspace and send a test event from there.
Signature check fails for every eventThe body was parsed and re-serialised, or the key was decodedVerify over the raw bytes; see Webhooks.
Events for one journey stopAn earlier event for that journey keeps failingEvents per journey are delivered in order; fix the failing delivery and the rest follow.
The same event arrives twiceA retry after a slow or failed answerDe-duplicate on event type, journeyId and created; see Webhooks.
403 on Get a journeyThe journey is not, or no longer, assigned to your company, or the id does not existCheck the id. If you received journeyFleetUnassignedEvent, the journey is no longer yours.
401 on Get a journeyThe API key is missing, wrong or expiredSee 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.

Was this helpful?