Skip to content

Webhook event

Journey status changed

A journey moved to a new status, for example from PENDING to CONFIRMED or to cancelled.

EVENTjourneyStatusChangedEventSent to partners and transfer companies

When it is sent

Sent on every status change of a journey. Partners and transfer companies each receive their own copy. For cancellations the new status depends on who pays: a partner receives CANCELLED_WITH_COSTS when the partner is charged, a transfer company when it is paid out; otherwise CANCELLED_FREE.

Transfer companies only receive it once the journey is assigned to them, and not for the early statuses NOT_PAID, AWAITING_APPROVAL and PENDING. Partners receive it when this event is enabled for their account.

Payload

The body is a JSON object with one key, journeyStatusChangedEvent, holding:

  • createdstring · date-time

    When the change happened (no time zone).

  • journeyIdinteger · int64

    The journey that changed. Fetch it with Get journey for full details.

  • previousStatusenum

    The status before the change.

    NOT_PAID
    The booking exists but has not been paid; the journey is not yet sent to a transfer company.
    AWAITING_APPROVAL
    Paid, waiting for an internal Transferz approval before it is processed.
    PENDING
    Paid and being processed; Transferz is looking for a transfer company.
    CONFIRMED
    A transfer company has been assigned and confirmed the journey.
    PLANNED
    A driver has been assigned.
    DRIVER_UNDERWAY
    The driver is on the way to the pickup point.
  • newStatusenum

    The status after the change.

    NOT_PAID
    The booking exists but has not been paid; the journey is not yet sent to a transfer company.
    AWAITING_APPROVAL
    Paid, waiting for an internal Transferz approval before it is processed.
    PENDING
    Paid and being processed; Transferz is looking for a transfer company.
    CONFIRMED
    A transfer company has been assigned and confirmed the journey.
    PLANNED
    A driver has been assigned.
    DRIVER_UNDERWAY
    The driver is on the way to the pickup point.

How to acknowledge

Respond with any 2xx status (200 or 204) within 20 seconds. Anything else counts as a failed delivery: redirects (3xx) are not followed, 4xx and 5xx (including 401 and 403) fail, and so do connection errors and timeouts. Verify the signature, store the event, respond, and do the slow work afterwards. The response body is ignored (it is kept in the delivery log).

Signature

Header Authorization, format HMAC <base64 signature>, HMAC-SHA256.

The signature is HMAC-SHA256 over the raw request body, using your webhook secret (the HMAC key shown in the portal) as UTF-8 bytes; the result is standard Base64 with padding. Verify against the raw body bytes exactly as received, before any JSON parsing, never against JSON you parsed and serialised again. The body is not formatted the way your framework would print it: it is one line with ": " after each key and ", " between items, and keys can come in a different order than in the example (shorter keys first). The example on this page is pretty-printed for reading. Compare with a constant-time comparison. Without a configured secret, events are sent unsigned.

Retries and ordering

Failed deliveries are retried with exponential backoff: about 2, 4, 8, 16 and 32 minutes, then hourly, until the number of attempts configured for your account is reached; after that the event is dropped. The number of attempts is set per company by Transferz and defaults to a single attempt, so ask for retries to be enabled before go-live. There is no event id header: an event can arrive more than once, so make your handling idempotent (for example on journeyId, the event key, created and the status values).

Events for the same journey are delivered one at a time, in the order they happened (see created). If one fails, later events for that journey wait until it succeeds or is dropped; events for other journeys continue. Expect a delay of about ten seconds between the change and the delivery.

Notes

  • Statuses can arrive in quick succession; always keep the one with the latest `created`.