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.

EventSent toWhen
journeyStatusChangedEventBothThe journey's status changed
journeyDriverAssignedEventPartnersA driver was assigned
journeyDriverVehicleAssignedEventPartnersA vehicle was assigned
journeyDriverPositionUpdatedEventPartnersThe driver's position was updated
journeyFleetAssignedEventTransfer companiesA journey was assigned to your fleet
journeyFleetUnassignedEventTransfer companiesA journey was taken away from your fleet
journeyExecutionDetailsUpdatedEventTransfer companiesPickup time, pickup or drop-off location changed
journeyTravellerInfoUpdatedEventTransfer companiesTraveller details changed
offerCreatedEventTransfer companiesA new offer is available (offer flow only)
offerStatusChangedEventTransfer companiesAn offer's status changed, for example it expired

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

Transfer companies set the staging webhook URL themselves 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.

Partners do the same in the workspace: set the staging webhook URL (HTTPS), read the signing key and see every delivery with its attempts. Changing the URL needs the partner permission to manage settings; ask the person who administers your company account if the workspace says you may not. Transferz still chooses which partner event types are switched on, 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
532 minutes
6 and later60 minutes

Each wait has up to one minute added at random. After the last allowed attempt, Transferz gives up on the event. The number of attempts is set per company.

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 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 have no unique id. Use the event type, journeyId and created together as the key, and ignore an event you have already stored.
  • 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?