# Webhooks

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

Section: Essentials · Last updated: 2026-11-18

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](https://developers.transferz.com/reference).

**For partners:**

| Event                                                                                                              | When                              |
| ------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| [`journeyStatusChangedEvent`](https://developers.transferz.com/reference/webhooks/journey-status-changed)          | The journey's status changed      |
| [`journeyDriverAssignedEvent`](https://developers.transferz.com/reference/webhooks/driver-assigned)                | A driver was assigned             |
| [`journeyDriverVehicleAssignedEvent`](https://developers.transferz.com/reference/webhooks/vehicle-assigned)        | A vehicle was assigned            |
| [`journeyDriverPositionUpdatedEvent`](https://developers.transferz.com/reference/webhooks/driver-position-updated) | The driver's position was updated |

**For transfer companies:**

| Event                                                                                                                | When                                             |
| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [`journeyStatusChangedEvent`](https://developers.transferz.com/reference/webhooks/journey-status-changed)            | The journey's status changed                     |
| [`journeyFleetAssignedEvent`](https://developers.transferz.com/reference/webhooks/journey-assigned)                  | A journey was assigned to your fleet             |
| [`journeyFleetUnassignedEvent`](https://developers.transferz.com/reference/webhooks/journey-unassigned)              | A journey was taken away from your fleet         |
| [`journeyExecutionDetailsUpdatedEvent`](https://developers.transferz.com/reference/webhooks/journey-details-updated) | Pickup time, pickup or drop-off location changed |
| [`journeyTravellerInfoUpdatedEvent`](https://developers.transferz.com/reference/webhooks/traveller-details-updated)  | Traveller 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](#verify-the-signature).

## Register your endpoint

**For transfer companies:**

Set the staging webhook URL yourself in the [workspace](https://developers.transferz.com/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](https://developers.transferz.com/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.1
Content-Type: application/json
Authorization: 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.

```javascript title="JavaScript"
import crypto from "node:crypto";
import express from "express";

const signingKey = process.env.TRANSFERZ_WEBHOOK_KEY;

export function isValidSignature(rawBody, header, key) {
  if (typeof header !== "string" || !header.startsWith("HMAC ")) return false;
  const expected = crypto.createHmac("sha256", key).update(rawBody).digest();
  const received = Buffer.from(header.slice(5), "base64");
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

const app = express();

// express.raw keeps the body as bytes, so the signature is computed over what was sent.
app.post("/webhooks/transferz", express.raw({ type: "application/json" }), (req, res) => {
  if (!isValidSignature(req.body, req.get("Authorization"), signingKey)) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  queueForProcessing(event); // store it; do the work after you answer
  res.sendStatus(204);
});
```

```java title="Java"
import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import java.security.MessageDigest;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class TransferzSignature {

  public static boolean isValid(byte[] rawBody, String header, String signingKey)
      throws GeneralSecurityException {
    if (header == null || !header.startsWith("HMAC ")) {
      return false;
    }
    byte[] received;
    try {
      received = Base64.getDecoder().decode(header.substring(5));
    } catch (IllegalArgumentException e) {
      return false;
    }
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(signingKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] expected = mac.doFinal(rawBody);
    return MessageDigest.isEqual(expected, received);
  }
}

// In a Spring controller, take the body as bytes:
// @PostMapping("/webhooks/transferz")
// ResponseEntity<Void> receive(@RequestBody byte[] body,
//     @RequestHeader(value = "Authorization", required = false) String signature) { ... }
```

```csharp title="C#"
using System.Security.Cryptography;
using System.Text;

public static class TransferzSignature
{
    public static bool IsValid(byte[] rawBody, string? header, string signingKey)
    {
        if (header is null || !header.StartsWith("HMAC ", StringComparison.Ordinal))
        {
            return false;
        }
        byte[] received;
        try
        {
            received = Convert.FromBase64String(header[5..]);
        }
        catch (FormatException)
        {
            return false;
        }
        byte[] expected = HMACSHA256.HashData(Encoding.UTF8.GetBytes(signingKey), rawBody);
        return CryptographicOperations.FixedTimeEquals(expected, received);
    }
}

// ASP.NET Core minimal API: read the raw body before parsing it.
// app.MapPost("/webhooks/transferz", async (HttpRequest request) =>
// {
//     using var buffer = new MemoryStream();
//     await request.Body.CopyToAsync(buffer);
//     var valid = TransferzSignature.IsValid(buffer.ToArray(),
//         request.Headers.Authorization, signingKey);
//     return valid ? Results.NoContent() : Results.Unauthorized();
// });
```

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

function transferz_signature_is_valid(string $rawBody, ?string $header, string $signingKey): bool
{
    if ($header === null || !str_starts_with($header, 'HMAC ')) {
        return false;
    }
    $expected = base64_encode(hash_hmac('sha256', $rawBody, $signingKey, true));
    return hash_equals($expected, substr($header, 5));
}

$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_AUTHORIZATION'] ?? null;

if (!transferz_signature_is_valid($rawBody, $header, getenv('TRANSFERZ_WEBHOOK_KEY'))) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
// Store the event, answer, then process it.
http_response_code(204);
```

```bash title="cURL"
# 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 attempt | Next attempt in about |
| -------------------- | --------------------- |
| 1                    | 2 minutes             |
| 2                    | 4 minutes             |
| 3                    | 8 minutes             |
| 4                    | 16 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](https://developers.transferz.com/reference/partners/get-journey) (partners) or
[Get a journey](https://developers.transferz.com/reference/transfer-companies/get-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](https://developers.transferz.com/workspace) delivery log shows the response your endpoint gave.

`created` is in UTC and has no time-zone offset; see [dates and time zones](https://developers.transferz.com/guides/essentials/conventions#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

| 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

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

### Certification cases

- [Partner: follow a journey](https://developers.transferz.com/certification/partners/follow-a-journey)
- [Partner: reject forged event](https://developers.transferz.com/certification/partners/reject-forged-event)
- [Transfer company: direct assignment](https://developers.transferz.com/certification/transfer-companies/direct-assignment)
