Webhook 规格

TrackEasy 主动推送物流轨迹更新事件的协议规格。

1. 注册 Webhook

POST /api/v1/webhooks
X-API-Key: tk_your_key
Content-Type: application/json

{
  "url": "https://your-server.com/webhook/trackeasy",
  "events": ["tracking_update", "tracking_delivered"]
}

响应中会返回 secret（whsec_xxx 格式）—— 仅此一次返回，请妥善保存用于验签。

{
  "code": 200, "meta": 200, "message": "请求响应成功。",
  "data": {
    "url": "https://your-server.com/webhook/trackeasy",
    "events": ["tracking_update", "tracking_delivered"],
    "enabled": true,
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0",  // ⚠️ 仅创建时返回
    "created_at": "2026-07-22T10:30:00",
    "signature_header": "X-Webhook-Signature: t=<ts>,v1=<hex> (sha256(ts + \".\" + body))"
  }
}

2. 事件类型

3. Payload 格式

{
  "event": "tracking_update",
  "created_at": "2026-07-22T10:30:45Z",
  "data": {
    "id": "f44cba625aa841eb7225f511",
    "tracking_number": "9205512345600001234567",
    "carrier": "usps",
    "status": "派送中",
    "events": [
      {
        "time": "2026-07-22T08:15:00Z",
        "location": "ALBUQUERQUE, NM 87105",
        "description": "Out for Delivery",
        "status": "out_for_delivery"
      },
      {
        "time": "2026-07-22T10:30:00Z",
        "location": "ALBUQUERQUE, NM 87105",
        "description": "Delivered, In/At Mailbox",
        "status": "delivered"
      }
    ]
  }
}

4. HTTP Headers

5. 签名验证（必做）

每个 webhook 请求都有签名 header：

X-Webhook-Signature: t=1753178400,v1=a37084ab68ae16b77db1f8463f31be9fcc965e2515e03efecf8139bb1e511b06
X-Webhook-Timestamp: 1753178400

算法： HMAC-SHA256(secret, timestamp + "." + body)

Python 验签示例

import hmac, hashlib, time
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_a1b2c3d4e5f6g7h8i9j0"  # 注册时返回

@app.post("/webhook/trackeasy")
def handle():
    sig_header = request.headers.get("X-Webhook-Signature", "")
    ts = request.headers.get("X-Webhook-Timestamp", "")
    body = request.get_data()

    # 1. 防 replay (5 分钟 drift)
    try:
        ts_int = int(ts)
    except ValueError:
        abort(400, "bad timestamp")
    if abs(time.time() - ts_int) > 300:
        abort(400, "timestamp drift")

    # 2. 验签
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        (ts + ".").encode() + body,
        hashlib.sha256,
    ).hexdigest()

    expected_header = f"t={ts},v1={expected}"
    if not hmac.compare_digest(sig_header, expected_header):
        abort(401, "bad signature")

    # 3. 处理事件
    event = request.json
    print(f"📦 {event['event']}: {event['data']['tracking_number']} → {event['data']['status']}")

    return "", 200  # 必须 2xx，否则会重试

Node.js 验签示例

const crypto = require('crypto');
const express = require('express');
const app = express();
app.use(express.raw({ type: 'application/json' }));

const WEBHOOK_SECRET = 'whsec_a1b2c3d4e5f6g7h8i9j0';

app.post('/webhook/trackeasy', (req, res) => {
  const sigHeader = req.headers['x-webhook-signature'] || '';
  const ts = req.headers['x-webhook-timestamp'] || '';
  const body = req.body;

  // 1. 防 replay
  if (Math.abs(Date.now()/1000 - parseInt(ts)) > 300) {
    return res.status(400).send('drift');
  }

  // 2. 验签
  const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(ts + '.' + body)
    .digest('hex');
  const expectedHeader = `t=${ts},v1=${expected}`;

  if (!crypto.timingSafeEqual(Buffer.from(sigHeader), Buffer.from(expectedHeader))) {
    return res.status(401).send('bad sig');
  }

  // 3. 处理
  const event = JSON.parse(body);
  console.log(`📦 ${event.event}: ${event.data.tracking_number}`);

  res.sendStatus(200);
});

6. 重试机制

失败定义：HTTP 状态码不在 200-299，或超时（10 秒）。

最多重试 14 次，指数回退 2^n × 30s：

14 次全失败后停止推送，不再重试。可调 GET /api/v1/webhooks/deliveries 看历史排查。

7. 安全要求

• 必须 HTTPS：生产环境禁止 HTTP（开发测试可用 HTTP）
• 禁私网 IP：注册时校验，禁止 127.0.0.1 / 10.x / 192.168.x / 172.16-31.x / 内网域名
• 5 分钟 timestamp drift：必须做时钟检查
• 验签必做：未验签的 webhook 视为不安全
• 幂等处理：同一 id + created_at 可能重投，客户端用 (id, ts) 去重

8. 测试

POST /api/v1/webhooks/test
X-API-Key: tk_your_key

响应：

{
  "code": 200, "meta": 200, "message": "请求响应成功。",
  "data": {
    "reachable": true,
    "http_status": 200,
    "response_ms": 142
  }
}

9. 投递历史

GET /api/v1/webhooks/deliveries
X-API-Key: tk_your_key

返回最近 50 条投递记录：

{
  "code": 200, "meta": 200, "message": "请求响应成功。",
  "data": {
    "count": 12,
    "items": [
      {
        "ts": "2026-07-22T10:30:45Z",
        "event": "tracking_delivered",
        "status_code": 200,
        "attempt": 1,
        "error": null
      },
      {
        "ts": "2026-07-22T09:15:00Z",
        "event": "tracking_update",
        "status_code": 500,
        "attempt": 3,
        "error": "Internal Server Error"
      }
    ]
  }
}

调试 webhook 问题时先看这个列表 —— 显示每次投递的状态码 + 错误。