Skip to content

Webhooks

Receive events from Transferz, verify their signature, acknowledge them, and handle retries, order and duplicates.

Updated · 5 min read

Transferz sends an HTTPS POST to your endpoint when something happens to one of your journeys. This guide shows how to register the endpoint, check that each event really comes from Transferz, and process events safely. You need an HTTPS endpoint that Transferz can reach.

Events you receive

Each event is a JSON object with one property, named after the event type. Full payloads are in the API reference.

For partners

EventWhen
journeyStatusChangedEventThe journey's status changed
journeyDriverAssignedEventA driver was assigned
journeyDriverVehicleAssignedEventA vehicle was assigned
journeyDriverPositionUpdatedEventThe driver's position was updated

For transfer companies

EventWhen
journeyStatusChangedEventThe journey's status changed
journeyFleetAssignedEventA journey was assigned to your fleet
journeyFleetUnassignedEventA journey was taken away from your fleet
journeyExecutionDetailsUpdatedEventPickup time, pickup or drop-off location changed
journeyTravellerInfoUpdatedEventTraveller details changed

This is what a status change looks like:

JSON
{  "journeyStatusChangedEvent": {    "created": "2026-11-02T09:14:27.512",    "journeyId": 4821937,    "newStatus": "PLANNED",    "previousStatus": "CONFIRMED"  }}

It is shown on several lines here for reading. On the wire the body is one line; see Verify the signature.

Register your endpoint

For transfer companies

Set the staging webhook URL yourself in the workspace. The URL must use HTTPS. The workspace also shows the signing key, can send a test event, and lists every delivery with its attempts.

For partners

Set the staging webhook URL (HTTPS) in the workspace. The workspace also shows the signing key and lists every delivery with its attempts.

Administrator accounts of your company can change the URL; ask your administrator if the workspace says you may not. The signing key is view-only: you can read and copy it, but not change it. Transferz sets which event types your company receives, so tell your Transferz contact which events you need.

Treat the signing key like a password. Store it in your secret store, not in source code.

Verify the signature

Every event has an Authorization header with an HMAC-SHA256 signature of the request body:

HTTP
POST /webhooks/transferz HTTP/1.1Content-Type: application/jsonAuthorization: HMAC 9hqLUdfYzf3M/NRmn29uunsArPs+cSpcQZoSqHgsrDc=

Transferz computes it like this:

  1. Take the request body exactly as sent: the raw bytes, before any JSON parsing. The body is one line with a space after every : and ,, and its keys may come in a different order than in the reference (shorter keys first). That is not what your JSON library prints, so never verify a re-serialised copy of the parsed event.
  2. Compute HMAC-SHA256 of the body. The key is your signing key as text, encoded as UTF-8. Do not decode the key from hex or Base64.
  3. Encode the result in Base64 and send it after HMAC (with one space).

To verify, compute the same value and compare it with the header in constant time. If they differ, answer 401 and do not process the event.

# Send a correctly signed test event to your own endpoint.BODY='{"journeyStatusChangedEvent": {"created": "2026-11-02T09:14:27.512", "journeyId": 4821937, "newStatus": "PLANNED", "previousStatus": "CONFIRMED"}}'SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$TRANSFERZ_WEBHOOK_KEY" -binary | base64)curl --request POST \  --url https://webhooks.example.com/transferz \  --header 'Content-Type: application/json' \  --header "Authorization: HMAC $SIGNATURE" \  --data-binary "$BODY"

Test your code with this example. With the signing key example-signing-key-not-for-production and the body below (one line, exactly as Transferz sends it, with a space after every : and ,), the header is HMAC 9hqLUdfYzf3M/NRmn29uunsArPs+cSpcQZoSqHgsrDc=.

JSON
{"journeyStatusChangedEvent": {"created": "2026-11-02T09:14:27.512", "journeyId": 4821937, "newStatus": "PLANNED", "previousStatus": "CONFIRMED"}}

Use the raw body

Most frameworks parse JSON before your code runs. If you serialise the parsed object again, spaces and field order change (JSON.stringify, Jackson, System.Text.Json and json_encode print no spaces) and the signature no longer matches. Read the raw bytes, verify, then parse.

Acknowledge the event

Answer with any 2xx status, for example 200 or 204, to acknowledge an event. Everything else counts as a failed delivery:

  • any 3xx, 4xx or 5xx status (Transferz does not follow redirects);
  • no connection within 10 seconds;
  • no response within 20 seconds.

Answer quickly. Store the event, answer 2xx, and do the work afterwards, for example from a queue. Do not call the Transferz API before you answer.

Retries

Transferz checks for events to deliver about every 10 seconds. After a failed attempt it waits before trying again, and doubles the wait each time:

After failed attemptNext attempt in about
12 minutes
24 minutes
38 minutes
416 minutes

Each wait has up to one minute added at random. Transferz delivers an event up to 5 times. After the fifth failed attempt, Transferz gives up on the event.

When an event was given up, fetch the current state of the journey with Get a journey (partners) or Get a journey (transfer companies).

Order

Events for the same journey arrive in the order they happened, by their created time. If an event for a journey fails, Transferz holds back the later events for that journey until the failed one is delivered or given up. Events for other journeys keep flowing.

This means one broken event blocks the updates for its journey. Fix failures quickly; the workspace delivery log shows the response your endpoint gave.

created is in UTC and has no time-zone offset; see dates and time zones.

Duplicates

You can receive the same event more than once, for example when your endpoint processed it but answered after 20 seconds. Make processing idempotent:

  • Events will carry a unique event id. Once it is present, use it as the key and ignore an event you have already stored. Until then, use the event type, journeyId and created together as the key.
  • For status events, compare newStatus with the status you have stored before acting on it.

Errors

ProblemCauseWhat to do
Every signature check failsThe body was re-serialised, or the key was decodedVerify over the raw bytes; use the key as UTF-8 text.
Events stop for one journeyAn earlier event for that journey keeps failingCheck the delivery log, fix the endpoint; the queue resumes by itself.
The same event is processed twiceA retry after a slow or failed answerDe-duplicate as described above.
No events at allURL not registered, or event types not enabledCheck the workspace (transfer companies) or ask Transferz (partners).

Was this helpful?