# Receive journeys by webhook

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

Section: Transfer companies · Last updated: 2026-11-15

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](https://developers.test.transferz.com/guides/essentials/webhooks). Set your webhook URL in
[Workspace › Webhooks](https://developers.test.transferz.com/workspace/staging/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`](https://developers.test.transferz.com/reference/webhooks/journey-assigned)                  | 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`](https://developers.test.transferz.com/reference/webhooks/journey-unassigned)              | A journey was taken away from your company.                                                                                                                      | Remove it; stop sending updates.                                                                                          |
| [`journeyStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-status-changed)            | The status of one of your journeys changed, including cancellations.                                                                                             | Update the status.                                                                                                        |
| [`journeyExecutionDetailsUpdatedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-details-updated) | The pickup time, pickup location or drop-off location changed.                                                                                                   | Re-plan.                                                                                                                  |
| [`journeyTravellerInfoUpdatedEvent`](https://developers.test.transferz.com/reference/webhooks/traveller-details-updated)  | Traveller details changed.                                                                                                                                       | Update the details.                                                                                                       |
| [`offerCreatedEvent`](https://developers.test.transferz.com/reference/webhooks/offer-created)                             | A new offer (offer flow only).                                                                                                                                   | See [Accept or decline offers](https://developers.test.transferz.com/guides/transfer-companies/accept-or-decline-offers). |
| [`offerStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/offer-status-changed)                | An offer's status changed (offer flow only).                                                                                                                     | Update or drop the offer.                                                                                                 |

Changes and cancellations are covered in
[Handle changes and cancellations](https://developers.test.transferz.com/guides/transfer-companies/handle-changes-and-cancellations).

## Step 1: Register your endpoint

In the [workspace](https://developers.test.transferz.com/workspace), save your staging webhook URL and copy the signing key. The URL must
use HTTPS. Implement the signature check from [Webhooks](https://developers.test.transferz.com/guides/essentials/webhooks#verify-the-signature)
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](https://developers.test.transferz.com/reference/webhooks/journey-assigned) 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](https://developers.test.transferz.com/guides/essentials/webhooks#acknowledge-the-event).

## 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:

**Request:** [`GET /journeys/488213`](https://developers.test.transferz.com/reference/transfer-companies/get-journey)

```bash title="cURL"
curl --request GET \
  --url 'https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213' \
  --header 'Accept: application/json' \
  --header 'X-API-Key: YOUR_STAGING_API_KEY'
```

```javascript title="JavaScript"
const response = await fetch("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213", {
  method: "GET",
  headers: {
    Accept: "application/json",
    "X-API-Key": "YOUR_STAGING_API_KEY",
  },
});

const data = await response.json();
console.log(response.status, data);
```

```java title="Java"
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213"))
        .header("Accept", "application/json")
        .header("X-API-Key", "YOUR_STAGING_API_KEY")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.statusCode());
    System.out.println(response.body());
  }
}
```

```csharp title="C#"
using System.Net.Http;
using System.Text;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("X-API-Key", "YOUR_STAGING_API_KEY");

using var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```php title="PHP"
<?php

$ch = curl_init('https://warpdrive.staging.transferz.com/transfercompanies/journeys/488213');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: YOUR_STAGING_API_KEY',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

echo $status, PHP_EOL, $response, PHP_EOL;
```

**Response (200):**

```json
{
  "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](https://developers.test.transferz.com/guides/transfer-companies/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](https://developers.test.transferz.com/guides/transfer-companies/assign-a-driver-and-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](https://developers.test.transferz.com/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](https://developers.test.transferz.com/guides/essentials/webhooks#verify-the-signature).                   |
| 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](https://developers.test.transferz.com/guides/essentials/webhooks#duplicates). |
| `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](https://developers.test.transferz.com/guides/get-started/authentication).                                                      |

If events were given up after the last attempt, catch up with
[Search journeys](https://developers.test.transferz.com/reference/transfer-companies/search-journeys) and the `updatedAfter` filter; see
[Look up and search journeys](https://developers.test.transferz.com/guides/transfer-companies/look-up-and-search-journeys#catch-up-after-missed-events).

> **To be confirmed by Transferz:** The default number of delivery attempts is still to be confirmed by Transferz.

## Related

### Endpoints

- [GET Get journey](https://developers.test.transferz.com/reference/transfer-companies/get-journey) (`GET /journeys/{id}`)

### Walk-through steps

- [Receive a journey](https://developers.test.transferz.com/walkthrough/transfer-company/receive-a-journey)
