# Webhooks

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

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

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.test.transferz.com/reference).

| Event                                                                                                                     | Sent to            | When                                              |
| ------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------- |
| [`journeyStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-status-changed)            | Both               | The journey's status changed                      |
| [`journeyDriverAssignedEvent`](https://developers.test.transferz.com/reference/webhooks/driver-assigned)                  | Partners           | A driver was assigned                             |
| [`journeyDriverVehicleAssignedEvent`](https://developers.test.transferz.com/reference/webhooks/vehicle-assigned)          | Partners           | A vehicle was assigned                            |
| [`journeyDriverPositionUpdatedEvent`](https://developers.test.transferz.com/reference/webhooks/driver-position-updated)   | Partners           | The driver's position was updated                 |
| [`journeyFleetAssignedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-assigned)                  | Transfer companies | A journey was assigned to your fleet              |
| [`journeyFleetUnassignedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-unassigned)              | Transfer companies | A journey was taken away from your fleet          |
| [`journeyExecutionDetailsUpdatedEvent`](https://developers.test.transferz.com/reference/webhooks/journey-details-updated) | Transfer companies | Pickup time, pickup or drop-off location changed  |
| [`journeyTravellerInfoUpdatedEvent`](https://developers.test.transferz.com/reference/webhooks/traveller-details-updated)  | Transfer companies | Traveller details changed                         |
| [`offerCreatedEvent`](https://developers.test.transferz.com/reference/webhooks/offer-created)                             | Transfer companies | A new offer is available (offer flow only)        |
| [`offerStatusChangedEvent`](https://developers.test.transferz.com/reference/webhooks/offer-status-changed)                | Transfer companies | An 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](#verify-the-signature).

## Register your endpoint

**Transfer companies** set the staging webhook URL themselves in the [workspace](https://developers.test.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.

**Partners** do the same in the [workspace](https://developers.test.transferz.com/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.

> **To be confirmed by Transferz:** Partner self-service of the webhook URL is built on the staging endpoints but not yet confirmed against live
> staging, and partners cannot yet choose their event types themselves.

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            |
| 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.

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

When an event was given up, fetch the current state of the journey with
[Get a journey](https://developers.test.transferz.com/reference/partners/get-journey) (partners) or
[Get a journey](https://developers.test.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.test.transferz.com/workspace) delivery log shows the response your endpoint gave.

`created` has no time-zone offset; see [dates and time zones](https://developers.test.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 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.

> **To be confirmed by Transferz:** A unique event id is still to be confirmed by Transferz.

## 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.test.transferz.com/reference/partners/get-journey) (`GET /journeys/{journeyId}`)
- [GET Get journey](https://developers.test.transferz.com/reference/transfer-companies/get-journey) (`GET /journeys/{id}`)
