Webhooks
Receive events from Transferz, verify their signature, acknowledge them, and handle retries, order and duplicates.
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.
| Event | Sent to | When |
|---|---|---|
journeyStatusChangedEvent | Both | The journey's status changed |
journeyDriverAssignedEvent | Partners | A driver was assigned |
journeyDriverVehicleAssignedEvent | Partners | A vehicle was assigned |
journeyDriverPositionUpdatedEvent | Partners | The driver's position was updated |
journeyFleetAssignedEvent | Transfer companies | A journey was assigned to your fleet |
journeyFleetUnassignedEvent | Transfer companies | A journey was taken away from your fleet |
journeyExecutionDetailsUpdatedEvent | Transfer companies | Pickup time, pickup or drop-off location changed |
journeyTravellerInfoUpdatedEvent | Transfer companies | Traveller details changed |
offerCreatedEvent | Transfer companies | A new offer is available (offer flow only) |
offerStatusChangedEvent | Transfer companies | An offer's status changed, for example it expired |
This is what a status change looks like:
{ "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:
POST /webhooks/transferz HTTP/1.1Content-Type: application/jsonAuthorization: HMAC 9hqLUdfYzf3M/NRmn29uunsArPs+cSpcQZoSqHgsrDc=Transferz computes it like this:
- 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. - 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.
- 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=.
{"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,4xxor5xxstatus (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 attempt | Next attempt in about |
|---|---|
| 1 | 2 minutes |
| 2 | 4 minutes |
| 3 | 8 minutes |
| 4 | 16 minutes |
| 5 | 32 minutes |
| 6 and later | 60 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,
journeyIdandcreatedtogether as the key, and ignore an event you have already stored. - For status events, compare
newStatuswith the status you have stored before acting on it.
Errors
| Problem | Cause | What to do |
|---|---|---|
| Every signature check fails | The body was re-serialised, or the key was decoded | Verify over the raw bytes; use the key as UTF-8 text. |
| Events stop for one journey | An earlier event for that journey keeps failing | Check the delivery log, fix the endpoint; the queue resumes by itself. |
| The same event is processed twice | A retry after a slow or failed answer | De-duplicate as described above. |
| No events at all | URL not registered, or event types not enabled | Check the workspace (transfer companies) or ask Transferz (partners). |
Related
Endpoints