Docs

Webhooks

Stracker calls your https endpoint when a trip is created, rescheduled, cancelled, started or completed. Each call is signed, retried when it fails, and kept in a delivery log you can read and replay.

The reference text of operations and fields below is generated from the API definition and is in English in every language.

Overview

  • An app subscribes with the API (webhooks:manage, client_credentials tokens only); an operator’s admin can also create subscriptions in Stracker. An app sees and changes only the subscriptions it owns, in the token’s tenant.
  • Apps receive the trip.* events, and only when the app holds trips:read. Billing events (invoice.*, payment.*, subscription.*, extension.*) go to an operator’s own subscriptions, never to an OAuth app.
  • Delivery is at least once and unordered. Deduplicate on the event id.
  • Deliveries need the operator to have the api extension.
  • Limits: 10 subscriptions per app in a tenant, 20 per tenant, 30 event types per subscription. The URL must be https, on port 443 or 8443, and resolve to a public address; it is checked when you save and on every connection.

Subscribe

curl
curl -sS https://api.stracker.vn/v1/webhooks/subscriptions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0c2f9d3a-61a1-4f0e-8d2b-5a0c1e7f4b22" \
  -d '{
    "name": "Trips to my dispatch system",
    "url": "https://example.com/stracker/webhooks",
    "events": ["trip.created", "trip.rescheduled", "trip.cancelled", "trip.started", "trip.completed"]
  }'
  • The answer holds the subscription and its signing secret, whsec_..., once. Store it now.
  • GET /v1/webhooks/event-types lists the event types your caller may subscribe to. Asking for another one is 403 WEBHOOK_EVENT_NOT_ALLOWED.
  • A refused URL is 400 WEBHOOK_URL_NOT_ALLOWED with the reason (scheme, port, credentials, fragment, unresolvable, private address).
  • Update with PATCH, pause with disable, resume with enable, remove with DELETE: see the reference.

What a delivery looks like

HTTP
POST /stracker/webhooks HTTP/1.1
Host: example.com
Content-Type: application/json
User-Agent: Stracker-Webhooks/1.0
Stracker-Event-Id: evt_01JD0000000000000000000000
Stracker-Event-Type: webhook.test
Stracker-Delivery-Id: 01JD00000000000000000000A1
Stracker-Delivery-Attempt: 1
Stracker-Webhook-Id: 42
Stracker-Signature: t=1763104324,v1=d351f50980e02348132b8097e68eeda996334f9c2b46b5fabbb8e26270e6bf9b

{"id":"evt_01JD0000000000000000000000","type":"webhook.test","createdAt":"2026-11-14T07:12:04.512Z","apiVersion":"2026-11-14","data":{"subscriptionId":42,"message":"Test event from Stracker"}}
HeaderDescription
Stracker-Event-IdThe event id, evt_ plus a ULID. Stable across retries and redelivery: dedupe on it.
Stracker-Event-TypeThe event type, for example trip.completed.
Stracker-Delivery-IdIdentifies this attempt. A new value for every attempt.
Stracker-Delivery-AttemptThe attempt number: 1 for the first delivery.
Stracker-Webhook-IdThe id of the subscription this delivery belongs to.
Stracker-Signaturet=<unix seconds>,v1=<hex>, with one v1 per live signing secret. See verify the signature.
X-Stracker-SignatureLegacy subscriptions only: sha256=<hex HMAC-SHA256 of the raw body>, without a timestamp. Prefer Stracker-Signature.
  • The body is the JSON envelope below, UTF-8, at most 64 KiB. The request has Content-Type: application/json and User-Agent: Stracker-Webhooks/1.0.
  • Answer with any 2xx within 10 seconds. Anything else is a failed attempt, including a timeout and a 3xx: redirects are not followed.
  • Acknowledge fast and work afterwards: put the event on your own queue.

The envelope

FieldDescription
idevt_ plus a ULID. Stable across retries and redelivery; dedupe on it.
typeThe event type.
createdAtWhen the event happened, ISO 8601 in UTC.
apiVersionThe date the payload shapes were last changed: 2026-11-14.
tenant{ "installId": "sti_..." } for a partner app’s subscriptions only; absent otherwise.
dataThe event payload. Its fields are listed per event below.
eventLegacy subscriptions only: the same as type.
occurredAtLegacy subscriptions only: the same as createdAt.
JSONA trip.completed delivery (illustrative values).
{
  "id": "evt_01JD...",
  "type": "trip.completed",
  "createdAt": "2026-11-14T07:12:04.512Z",
  "apiVersion": "2026-11-14",
  "tenant": { "installId": "sti_..." },
  "data": {
    "trip": {
      "id": 91,
      "code": "TR-2026-1114-004",
      "routeId": 4,
      "date": "2026-11-14",
      "status": "completed",
      "plannedStartTime": "07:00:00",
      "plannedEndTime": "07:45:00",
      "actualStartAt": "2026-11-14T00:02:10.000Z",
      "actualEndAt": "2026-11-14T00:47:31.000Z",
      "driverId": 3,
      "vehicleId": 7,
      "cancelReason": null
    }
  }
}

Instants are ISO 8601 in UTC. A trip’s date is the service day in the operator’s local time (YYYY-MM-DD) and planned times are times of day (HH:mm:ss). The data of each event is listed under events.

Verify the signature

Anyone can post to your URL, so check every request came from Stracker. The Stracker-Signature header is t=<unix seconds>,v1=<hex>:

  1. Take the raw request body exactly as received. Do not parse and re-serialise it: one changed space breaks the signature.
  2. Read t and every v1 from the header. During a secret rotation there are two v1 values.
  3. Reject the request when |now - t| is more than 300 seconds. This stops an old request being replayed.
  4. Compute HMAC-SHA256(secret, t + "." + raw body) and write it as lowercase hex.
  5. Compare it with each v1 in constant time. Accept when any one matches.
Node.js
const crypto = require('node:crypto');

const TOLERANCE_SECONDS = 300;

/**
 * rawBody: the request body exactly as received (Buffer or string), never JSON.stringify(parsedBody).
 * header:  the value of the Stracker-Signature header.
 * secret:  the subscription's signing secret (whsec_...).
 */
function verifyStrackerSignature(rawBody, header, secret, nowSeconds = Math.floor(Date.now() / 1000)) {
  let timestamp = null;
  const candidates = [];
  for (const part of String(header ?? '').split(',')) {
    const at = part.indexOf('=');
    if (at < 0) continue;
    const key = part.slice(0, at).trim();
    const value = part.slice(at + 1).trim();
    if (key === 't' && /^\d+$/.test(value)) timestamp = Number(value);
    if (key === 'v1' && /^[0-9a-f]+$/.test(value)) candidates.push(value); // one per live secret
  }
  if (timestamp === null || candidates.length === 0) return false;
  if (Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) return false; // replay protection

  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody, 'utf8');
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.`).update(body).digest();
  return candidates.some((candidate) => {
    const given = Buffer.from(candidate, 'hex');
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}
Python
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify_stracker_signature(raw_body: bytes, header: str, secret: str, now: float | None = None) -> bool:
    """raw_body: the request body exactly as received (bytes), never json.dumps(parsed_body)."""
    timestamp = None
    candidates = []
    for part in (header or "").split(","):
        key, sep, value = part.strip().partition("=")
        if not sep:
            continue
        if key == "t" and value.isdigit():
            timestamp = int(value)
        elif key == "v1" and value:
            candidates.append(value)  # one per live secret during a rotation
    if timestamp is None or not candidates:
        return False
    if abs((time.time() if now is None else now) - timestamp) > TOLERANCE_SECONDS:
        return False  # replay protection

    expected = hmac.new(
        secret.encode("utf-8"), str(timestamp).encode("ascii") + b"." + raw_body, hashlib.sha256
    ).hexdigest()
    return any(hmac.compare_digest(candidate, expected) for candidate in candidates)
PHP
<?php

const STRACKER_TOLERANCE_SECONDS = 300;

/**
 * $rawBody: the request body exactly as received (file_get_contents('php://input')),
 * never json_encode(json_decode($body)).
 */
function verifyStrackerSignature(string $rawBody, string $header, string $secret, ?int $now = null): bool
{
    $timestamp = null;
    $candidates = [];
    foreach (explode(',', $header) as $part) {
        $pair = explode('=', trim($part), 2);
        if (count($pair) !== 2) {
            continue;
        }
        [$key, $value] = $pair;
        if ($key === 't' && ctype_digit($value)) {
            $timestamp = (int) $value;
        } elseif ($key === 'v1' && $value !== '') {
            $candidates[] = $value; // one per live secret during a rotation
        }
    }
    if ($timestamp === null || $candidates === []) {
        return false;
    }
    if (abs(($now ?? time()) - $timestamp) > STRACKER_TOLERANCE_SECONDS) {
        return false; // replay protection
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    foreach ($candidates as $candidate) {
        if (hash_equals($expected, $candidate)) {
            return true;
        }
    }
    return false;
}

Wire it into your handler. Each sample reads the raw bytes, verifies, then acknowledges:

Node.js (Express)
const express = require('express');
const app = express();

// Keep the raw bytes: the signature covers them, not the parsed JSON.
app.post('/stracker/webhooks', express.raw({ type: 'application/json', limit: '128kb' }), (req, res) => {
  const ok = verifyStrackerSignature(req.body, req.get('Stracker-Signature'), process.env.STRACKER_WEBHOOK_SECRET);
  if (!ok) return res.status(400).send('invalid signature');

  const event = JSON.parse(req.body.toString('utf8'));
  // Dedupe on event.id (deliveries are at least once), then do the work out of band.
  // queue.add({ id: event.id, type: event.type, data: event.data });
  res.status(204).end(); // answer 2xx within 10 seconds
});

app.listen(3000);
Python (Flask)
import json
import os

from flask import Flask, request

app = Flask(__name__)


@app.post("/stracker/webhooks")
def stracker_webhook():
    raw = request.get_data()  # the raw bytes, not request.get_json()
    header = request.headers.get("Stracker-Signature", "")
    if not verify_stracker_signature(raw, header, os.environ["STRACKER_WEBHOOK_SECRET"]):
        return "invalid signature", 400

    event = json.loads(raw)
    # Dedupe on event["id"] (deliveries are at least once), then do the work out of band.
    return "", 204  # answer 2xx within 10 seconds
PHP
<?php

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

if (!verifyStrackerSignature($rawBody, $header, getenv('STRACKER_WEBHOOK_SECRET'))) {
    http_response_code(400);
    exit('invalid signature');
}

$event = json_decode($rawBody, true);
// Dedupe on $event['id'] (deliveries are at least once), then do the work out of band.
http_response_code(204); // answer 2xx within 10 seconds

A test vector to check your code

Your implementation must produce this exact v1. It was computed with an independent HMAC implementation and is pinned by Stracker’s own unit tests; the samples above are tested against it.

Test vector
secret    whsec_test_vector_secret
t         1763104324
body      {"id":"evt_01JD0000000000000000000000","type":"webhook.test","createdAt":"2026-11-14T07:12:04.512Z","apiVersion":"2026-11-14","data":{"subscriptionId":42,"message":"Test event from Stracker"}}

signed    "1763104324." + body
v1        d351f50980e02348132b8097e68eeda996334f9c2b46b5fabbb8e26270e6bf9b
header    t=1763104324,v1=d351f50980e02348132b8097e68eeda996334f9c2b46b5fabbb8e26270e6bf9b

Retries

An attempt fails on a non-2xx answer, a timeout or a network error. Stracker then retries on this schedule, each wait spread by up to ±10 % so a recovering endpoint is not hit all at once. A message gets 7 attempts over about 32 hours 36 minutes; after the last one it is marked failed.

AttemptWait before itTime since the first attempt
1immediately0
21 minute1 minute
35 minutes6 minutes
430 minutes36 minutes
52 hours156 minutes
66 hours516 minutes
71 day1956 minutes

Automatic disabling

After 25 failed attempts in a row, across messages, and a failing streak of at least 24 hours, Stracker disables the subscription (disabledReason: "auto_failures") and emails the users in the tenant who manage webhooks. A burst of failures inside a day never disables it. Fix your endpoint, then POST /v1/webhooks/subscriptions/{id}/enable: the URL is checked again and the counters reset. Messages still waiting when it was disabled are cancelled, and events that happen while it is disabled are not delivered later: reconcile with GET /v1/trips.

Delivery log and redelivery

  • GET /v1/webhooks/messages lists messages (pending, delivered, failed, cancelled); GET /v1/webhooks/messages/{id} adds every attempt with its status class, latency, a short response excerpt and the exact payload.
  • POST /v1/webhooks/messages/{id}/redeliver queues one more attempt now, with the same event id. A message that is too old is 410 WEBHOOK_MESSAGE_EXPIRED.
  • Messages are kept 30 days and attempts 90 days.
curl
# Find the message, then queue one more attempt now
curl -sS "https://api.stracker.vn/v1/webhooks/messages?status=failed" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
curl -sS -X POST https://api.stracker.vn/v1/webhooks/messages/$MESSAGE_ID/redeliver \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Rotating the secret

POST /v1/webhooks/subscriptions/{id}/rotate-secret returns a new secret, once. For 24 hours every delivery is signed with both secrets (two v1 values), so you can switch without a gap. Send { "revokePreviousNow": true } to drop the old one at once. A replay of the same request with an Idempotency-Key returns no secret.

Test event

POST /v1/webhooks/subscriptions/{id}/test sends a signed webhook.test event and returns whether it was delivered, the status code and the latency. It is limited to 10 per minute per subscription.

curl
# Send a webhook.test event to the endpoint and read the outcome
curl -sS -X POST https://api.stracker.vn/v1/webhooks/subscriptions/$SUBSCRIPTION_ID/test \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Limits by design

  • No trip.created for trips made in bulk or generated by Stracker: only a single trip created through the create-trip path emits it. There are no events for deleting a trip or for assigning a driver.
  • An event can be lost if the Stracker process stops between saving a change and publishing the event; publishing never blocks or undoes a trip change. Reconcile now and then with GET /v1/trips.
  • There is no ordering guarantee. Use the trip data in the event, or fetch the trip, rather than the order of arrival.

Events

trip.created Trip created

  • Delivered to The operator’s own subscriptions and apps holding the scope below
  • Scope trips:read

Fields of data

FieldTypeDescription
triprequiredobject
trip.idrequiredinteger
trip.coderequiredstring | nullnullable
trip.routeIdrequiredinteger
trip.daterequiredstringpattern ^\d{4}-\d{2}-\d{2}$
trip.statusrequiredstringValues: scheduledin_progresscompletedcancelled
trip.plannedStartTimerequiredstring | nullnullable
trip.plannedEndTimerequiredstring | nullnullable
trip.actualStartAtrequiredstring | nullnullable
trip.actualEndAtrequiredstring | nullnullable
trip.driverIdrequiredinteger | nullnullable
trip.vehicleIdrequiredinteger | nullnullable
trip.cancelReasonnull
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "trip": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "code": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 60
            },
            {
              "type": "null"
            }
          ]
        },
        "routeId": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "status": {
          "type": "string",
          "enum": [
            "scheduled",
            "in_progress",
            "completed",
            "cancelled"
          ]
        },
        "plannedStartTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "plannedEndTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualStartAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualEndAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "driverId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "vehicleId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "cancelReason": {
          "type": "null"
        }
      },
      "required": [
        "id",
        "code",
        "routeId",
        "date",
        "status",
        "plannedStartTime",
        "plannedEndTime",
        "actualStartAt",
        "actualEndAt",
        "driverId",
        "vehicleId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "trip"
  ],
  "additionalProperties": false
}

trip.rescheduled Trip rescheduled

  • Delivered to The operator’s own subscriptions and apps holding the scope below
  • Scope trips:read

Fields of data

FieldTypeDescription
triprequiredobject
trip.idrequiredinteger
trip.coderequiredstring | nullnullable
trip.routeIdrequiredinteger
trip.daterequiredstringpattern ^\d{4}-\d{2}-\d{2}$
trip.statusrequiredstringValues: scheduledin_progresscompletedcancelled
trip.plannedStartTimerequiredstring | nullnullable
trip.plannedEndTimerequiredstring | nullnullable
trip.actualStartAtrequiredstring | nullnullable
trip.actualEndAtrequiredstring | nullnullable
trip.driverIdrequiredinteger | nullnullable
trip.vehicleIdrequiredinteger | nullnullable
trip.previousPlannedStartTimerequiredstring | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "trip": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "code": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 60
            },
            {
              "type": "null"
            }
          ]
        },
        "routeId": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "status": {
          "type": "string",
          "enum": [
            "scheduled",
            "in_progress",
            "completed",
            "cancelled"
          ]
        },
        "plannedStartTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "plannedEndTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualStartAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualEndAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "driverId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "vehicleId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "previousPlannedStartTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "code",
        "routeId",
        "date",
        "status",
        "plannedStartTime",
        "plannedEndTime",
        "actualStartAt",
        "actualEndAt",
        "driverId",
        "vehicleId",
        "previousPlannedStartTime"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "trip"
  ],
  "additionalProperties": false
}

trip.cancelled Trip cancelled

  • Delivered to The operator’s own subscriptions and apps holding the scope below
  • Scope trips:read

Fields of data

FieldTypeDescription
triprequiredobject
trip.idrequiredinteger
trip.coderequiredstring | nullnullable
trip.routeIdrequiredinteger
trip.daterequiredstringpattern ^\d{4}-\d{2}-\d{2}$
trip.statusrequiredstringValues: scheduledin_progresscompletedcancelled
trip.plannedStartTimerequiredstring | nullnullable
trip.plannedEndTimerequiredstring | nullnullable
trip.actualStartAtrequiredstring | nullnullable
trip.actualEndAtrequiredstring | nullnullable
trip.driverIdrequiredinteger | nullnullable
trip.vehicleIdrequiredinteger | nullnullable
trip.cancelReasonrequiredstring | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "trip": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "code": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 60
            },
            {
              "type": "null"
            }
          ]
        },
        "routeId": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "status": {
          "type": "string",
          "enum": [
            "scheduled",
            "in_progress",
            "completed",
            "cancelled"
          ]
        },
        "plannedStartTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "plannedEndTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualStartAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualEndAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "driverId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "vehicleId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "cancelReason": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 500
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "code",
        "routeId",
        "date",
        "status",
        "plannedStartTime",
        "plannedEndTime",
        "actualStartAt",
        "actualEndAt",
        "driverId",
        "vehicleId",
        "cancelReason"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "trip"
  ],
  "additionalProperties": false
}

trip.started Trip started

  • Delivered to The operator’s own subscriptions and apps holding the scope below
  • Scope trips:read

Fields of data

FieldTypeDescription
triprequiredobject
trip.idrequiredinteger
trip.coderequiredstring | nullnullable
trip.routeIdrequiredinteger
trip.daterequiredstringpattern ^\d{4}-\d{2}-\d{2}$
trip.statusrequiredstringValues: scheduledin_progresscompletedcancelled
trip.plannedStartTimerequiredstring | nullnullable
trip.plannedEndTimerequiredstring | nullnullable
trip.actualStartAtrequiredstring | nullnullable
trip.actualEndAtrequiredstring | nullnullable
trip.driverIdrequiredinteger | nullnullable
trip.vehicleIdrequiredinteger | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "trip": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "code": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 60
            },
            {
              "type": "null"
            }
          ]
        },
        "routeId": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "status": {
          "type": "string",
          "enum": [
            "scheduled",
            "in_progress",
            "completed",
            "cancelled"
          ]
        },
        "plannedStartTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "plannedEndTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualStartAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualEndAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "driverId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "vehicleId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "code",
        "routeId",
        "date",
        "status",
        "plannedStartTime",
        "plannedEndTime",
        "actualStartAt",
        "actualEndAt",
        "driverId",
        "vehicleId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "trip"
  ],
  "additionalProperties": false
}

trip.completed Trip completed

  • Delivered to The operator’s own subscriptions and apps holding the scope below
  • Scope trips:read

Fields of data

FieldTypeDescription
triprequiredobject
trip.idrequiredinteger
trip.coderequiredstring | nullnullable
trip.routeIdrequiredinteger
trip.daterequiredstringpattern ^\d{4}-\d{2}-\d{2}$
trip.statusrequiredstringValues: scheduledin_progresscompletedcancelled
trip.plannedStartTimerequiredstring | nullnullable
trip.plannedEndTimerequiredstring | nullnullable
trip.actualStartAtrequiredstring | nullnullable
trip.actualEndAtrequiredstring | nullnullable
trip.driverIdrequiredinteger | nullnullable
trip.vehicleIdrequiredinteger | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "trip": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "code": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 60
            },
            {
              "type": "null"
            }
          ]
        },
        "routeId": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "date": {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        "status": {
          "type": "string",
          "enum": [
            "scheduled",
            "in_progress",
            "completed",
            "cancelled"
          ]
        },
        "plannedStartTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "plannedEndTime": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualStartAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "actualEndAt": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
            },
            {
              "type": "null"
            }
          ]
        },
        "driverId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        },
        "vehicleId": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "required": [
        "id",
        "code",
        "routeId",
        "date",
        "status",
        "plannedStartTime",
        "plannedEndTime",
        "actualStartAt",
        "actualEndAt",
        "driverId",
        "vehicleId"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "trip"
  ],
  "additionalProperties": false
}

invoice.created Invoice created

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
invoiceIdrequirednumber | string
clientIdnumber | string | nullnullable
totalAmountnumber | string | nullnullable
amountnumber | string | nullnullable
paymentIdnumber | string | nullnullable
pspRefundIdstring | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "invoiceId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "clientId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "totalAmount": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "amount": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "paymentId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "pspRefundId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "invoiceId"
  ],
  "additionalProperties": {}
}

invoice.paid Invoice paid

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
invoiceIdrequirednumber | string
clientIdnumber | string | nullnullable
totalAmountnumber | string | nullnullable
amountnumber | string | nullnullable
paymentIdnumber | string | nullnullable
pspRefundIdstring | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "invoiceId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "clientId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "totalAmount": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "amount": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "paymentId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "pspRefundId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "invoiceId"
  ],
  "additionalProperties": {}
}

invoice.payment_failed Invoice payment failed

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
invoiceIdrequirednumber | string
clientIdnumber | string | nullnullable
totalAmountnumber | string | nullnullable
amountnumber | string | nullnullable
paymentIdnumber | string | nullnullable
pspRefundIdstring | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "invoiceId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "clientId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "totalAmount": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "amount": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "paymentId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "pspRefundId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "invoiceId"
  ],
  "additionalProperties": {}
}

invoice.refunded Invoice refunded

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
invoiceIdrequirednumber | string
clientIdnumber | string | nullnullable
totalAmountnumber | string | nullnullable
amountnumber | string | nullnullable
paymentIdnumber | string | nullnullable
pspRefundIdstring | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "invoiceId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "clientId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "totalAmount": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "amount": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "paymentId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "pspRefundId": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "invoiceId"
  ],
  "additionalProperties": {}
}

payment.completed Payment completed

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
invoiceIdrequirednumber | string
clientIdnumber | string | nullnullable
paymentIdrequirednumber | string
succeededboolean | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "invoiceId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "clientId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "paymentId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "succeeded": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "invoiceId",
    "paymentId"
  ],
  "additionalProperties": {}
}

payment.failed Payment failed

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
invoiceIdrequirednumber | string
clientIdnumber | string | nullnullable
paymentIdrequirednumber | string
succeededboolean | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "invoiceId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "clientId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "paymentId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "succeeded": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "invoiceId",
    "paymentId"
  ],
  "additionalProperties": {}
}

subscription.created Subscription created

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
subscriptionIdrequirednumber | string
clientIdnumber | string | nullnullable
planIdnumber | string | nullnullable
planVersionIdnumber | string | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "clientId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "planId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "planVersionId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "subscriptionId"
  ],
  "additionalProperties": {}
}

subscription.upgraded Subscription upgraded

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
subscriptionIdrequirednumber | string
clientIdnumber | string | nullnullable
planIdnumber | string | nullnullable
planVersionIdnumber | string | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "clientId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "planId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "planVersionId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "subscriptionId"
  ],
  "additionalProperties": {}
}

subscription.canceled Subscription canceled

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
subscriptionIdrequirednumber | string
clientIdnumber | string | nullnullable
planIdnumber | string | nullnullable
planVersionIdnumber | string | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "clientId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "planId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "planVersionId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "subscriptionId"
  ],
  "additionalProperties": {}
}

extension.installed Extension installed

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
clientIdrequirednumber | string
extensionIdrequirednumber | string
installedVersionIdnumber | string | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "clientId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "extensionId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "installedVersionId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "clientId",
    "extensionId"
  ],
  "additionalProperties": {}
}

extension.upgraded Extension upgraded

  • Delivered to The operator’s own subscriptions only, never an OAuth app

Fields of data

FieldTypeDescription
clientIdrequirednumber | string
extensionIdrequirednumber | string
installedVersionIdnumber | string | nullnullable
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "clientId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "extensionId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "installedVersionId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "string"
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "clientId",
    "extensionId"
  ],
  "additionalProperties": {}
}

webhook.test Test event

  • Delivered to The subscription that was tested

Fields of data

FieldTypeDescription
subscriptionIdrequirednumber | string
messagerequiredstring
JSON Schema of data
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "subscriptionId": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ]
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "subscriptionId",
    "message"
  ],
  "additionalProperties": false
}