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.
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>:
Take the raw request body exactly as received. Do not parse and re-serialise it: one changed space breaks the signature.
Read t and every v1 from the header. During a secret rotation there are two v1 values.
Reject the request when |now - t| is more than 300 seconds. This stops an old request being replayed.
Compute HMAC-SHA256(secret, t + "." + raw body) and write it as lowercase hex.
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.
Attempt
Wait before it
Time since the first attempt
1
immediately
0
2
1 minute
1 minute
3
5 minutes
6 minutes
4
30 minutes
36 minutes
5
2 hours
156 minutes
6
6 hours
516 minutes
7
1 day
1956 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.