Stracker gọi vào endpoint https của bạn khi một chuyến được tạo, dời lịch, hủy, bắt đầu hoặc hoàn thành. Mỗi lệnh gọi được ký, được thử lại khi lỗi và lưu trong nhật ký gửi mà bạn đọc và gửi lại được.
Phần mô tả các thao tác và trường dưới đây được sinh tự động từ định nghĩa API nên giữ nguyên tiếng Anh ở mọi ngôn ngữ.
Tổng quan
Ứng dụng đăng ký bằng API (webhooks:manage, chỉ với token client_credentials); quản trị viên của đơn vị cũng có thể tạo subscription trong Stracker. Ứng dụng chỉ thấy và đổi các subscription do chính nó sở hữu, trong tenant của token.
Ứng dụng nhận các sự kiện trip.*, và chỉ khi có trips:read. Sự kiện thanh toán (invoice.*, payment.*, subscription.*, extension.*) chỉ gửi cho subscription của chính đơn vị, không bao giờ cho ứng dụng OAuth.
Gửi ít nhất một lần và không đảm bảo thứ tự. Loại trùng theo id của sự kiện.
Việc gửi cần đơn vị có tiện ích api.
Giới hạn: 10 subscription mỗi ứng dụng trong một tenant, 20 mỗi tenant, 30 loại sự kiện mỗi subscription. URL phải là https, cổng 443 or 8443 và phân giải ra địa chỉ công khai; được kiểm tra khi bạn lưu và ở mỗi lần kết nối.
Thời điểm là ISO 8601 theo UTC. date của chuyến là ngày phục vụ theo giờ địa phương của đơn vị (YYYY-MM-DD) và giờ kế hoạch là giờ trong ngày (HH:mm:ss). data của từng sự kiện được liệt kê ở mục sự kiện.
Xác minh chữ ký
Ai cũng có thể gửi vào URL của bạn, nên hãy kiểm tra mọi yêu cầu đều đến từ Stracker. Header Stracker-Signature có dạng t=<giây unix>,v1=<hex>:
Lấy nội dung yêu cầu thô đúng như nhận được. Đừng phân tích rồi tuần tự hóa lại: đổi một dấu cách là hỏng chữ ký.
Đọc t và mọi v1 từ header. Khi đổi khóa bí mật có hai giá trị v1.
Từ chối yêu cầu nếu |bây giờ - t| lớn hơn 300 giây. Điều này chặn việc phát lại yêu cầu cũ.
Tính HMAC-SHA256(secret, t + "." + nội dung thô) và viết dưới dạng hex chữ thường.
So sánh với từng v1 theo thời gian không đổi. Chấp nhận khi có một giá trị khớp.
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;
}
Nối vào trình xử lý của bạn. Mỗi ví dụ đọc byte thô, xác minh rồi xác nhận:
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
Bộ dữ liệu thử để kiểm tra mã của bạn
Mã của bạn phải ra đúng v1 này. Giá trị được tính bằng một bản cài đặt HMAC độc lập và được các bài kiểm thử đơn vị của Stracker cố định lại; các ví dụ ở trên đã được kiểm thử với nó.
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
Thử lại
Một lần gửi thất bại khi trả lời không phải 2xx, hết thời gian chờ hoặc lỗi mạng. Stracker khi đó thử lại theo lịch dưới đây, mỗi quãng chờ lệch tới ±10 % để endpoint đang hồi phục không bị dồn dập. Một thông điệp có 7 lần gửi trong khoảng 32 giờ 36 phút; sau lần cuối nó bị đánh dấu failed.
Lần gửi
Chờ trước lần này
Từ lần gửi đầu
1
ngay lập tức
0
2
1 phút
1 phút
3
5 phút
6 phút
4
30 phút
36 phút
5
2 giờ
156 phút
6
6 giờ
516 phút
7
1 ngày
1956 phút
Tự động tắt
Sau 25 lần gửi thất bại liên tiếp, tính qua các thông điệp, và chuỗi thất bại kéo dài ít nhất 24 giờ, Stracker tắt subscription (disabledReason: "auto_failures") và gửi email cho những người dùng quản lý webhook trong tenant. Một loạt lỗi trong vòng một ngày không bao giờ làm nó bị tắt. Hãy sửa endpoint rồi POST /v1/webhooks/subscriptions/{id}/enable: URL được kiểm tra lại và bộ đếm được đặt lại. Các thông điệp đang chờ lúc bị tắt bị hủy, và sự kiện xảy ra khi đang tắt sẽ không được gửi bù: hãy đối soát bằng GET /v1/trips.
Nhật ký gửi và gửi lại
GET /v1/webhooks/messages liệt kê thông điệp (pending, delivered, failed, cancelled); GET /v1/webhooks/messages/{id} thêm từng lần gửi với nhóm trạng thái, độ trễ, đoạn trích ngắn của phản hồi và payload chính xác.
POST /v1/webhooks/messages/{id}/redeliver xếp thêm một lần gửi ngay, với cùng id sự kiện. Thông điệp quá cũ là 410 WEBHOOK_MESSAGE_EXPIRED.
Thông điệp được giữ 30 ngày và các lần gửi được giữ 90 ngày.
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"
Đổi khóa bí mật
POST /v1/webhooks/subscriptions/{id}/rotate-secret trả về khóa mới, một lần. Trong 24 giờ mọi lần gửi được ký bằng cả hai khóa (hai giá trị v1), nên bạn chuyển đổi không bị gián đoạn. Gửi { "revokePreviousNow": true } để bỏ khóa cũ ngay. Phát lại cùng yêu cầu với Idempotency-Key không trả khóa bí mật.
Sự kiện thử
POST /v1/webhooks/subscriptions/{id}/test gửi một sự kiện webhook.test có chữ ký và trả về việc có gửi được không, mã trạng thái và độ trễ. Giới hạn 10 lần mỗi phút cho mỗi 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"
Giới hạn có chủ đích
Không có trip.created cho chuyến tạo hàng loạt hoặc do Stracker sinh ra: chỉ chuyến đơn tạo qua đường tạo chuyến mới phát sự kiện này. Không có sự kiện cho việc xóa chuyến hay phân tài xế.
Một sự kiện có thể mất nếu tiến trình Stracker dừng giữa lúc lưu thay đổi và lúc phát sự kiện; việc phát không bao giờ chặn hay hoàn tác thay đổi chuyến. Thỉnh thoảng hãy đối soát bằng GET /v1/trips.
Không bảo đảm thứ tự. Hãy dùng dữ liệu chuyến trong sự kiện, hoặc tải lại chuyến, thay vì dựa vào thứ tự đến.