跳转到内容

Webhook

使用 Webhook 就不必反复轮询。只要一票货上您可见的内容发生变化,我们就把事件推送到您提供的地址,通常在一分钟内送达。

  1. 向您的 Golden Arcus 对接人提供一个公网可访问的 https 地址,例如 https://erp.example.com/ga/webhooks。
  2. 我们会把该地址的签名密钥提供给您,以 whsec_ 开头。
  3. 开通后,您账号下的每个事件都会推送到该地址。
POST /ga/webhooks HTTP/1.1
Host: erp.example.com
Content-Type: application/json
User-Agent: GoldenArcus-Webhooks/1
webhook-id: evt_e3-01JCX7M4Z9Q8R6T5V3W2Y1N0AB
webhook-timestamp: 1794521112
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{"id":"evt_e3-01JCX7M4Z9Q8R6T5V3W2Y1N0AB","object":"event", ...}

请求体与 GET /v1/events 返回的事件对象相同,包含完整的货物数据。请求头遵循 Standard Webhooks 规范,可直接使用该规范的各语言库。

  • 请在 10 秒内返回任意 2xx 状态码,响应体会被忽略。
  • 耗时的处理请放到响应之后:先保存事件并返回,再异步处理。
  • 返回其他状态码、重定向或超时,都视为推送失败,我们会重试。

推送失败后,我们会在 1 分钟、5 分钟、30 分钟、2 小时、6 小时、12 小时、24 小时、24 小时后依次重试,约三天内最多推送九次。如果最后一次仍然失败,我们会停用该地址并停止推送。数据不会丢失:这些事件在 GET /v1/events 中保留 90 天。您的服务恢复后请告知我们,我们会重新启用。

  • 重试时 webhook-id 不变。 如果该 id 已处理过,直接返回 2xx 即可,无需重复处理。
  • 推送可能乱序到达。 每次推送都包含完整的货物数据,请以 updated_at 最新的一份为准。

处理推送之前,请先校验签名。签名是对以下内容计算的 HMAC-SHA256:

{webhook-id}.{webhook-timestamp}.{原始请求体}

密钥为您的签名密钥(whsec_ 之后的部分,需先做 base64 解码);签名的格式为 v1, 加上计算结果的 base64 编码。计算时请使用收到的原始请求体,不要先解析 JSON。时间戳与您服务器时间相差超过五分钟的推送,请拒绝。

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(secret, headers, rawBody) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key)
.update(`${id}.${timestamp}.${rawBody}`)
.digest('base64');
return String(headers['webhook-signature'])
.split(' ')
.some((part) => {
const [version, signature = ''] = part.split(',');
return (
version === 'v1' &&
signature.length === expected.length &&
timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
);
});
}

可以用 Standard Webhooks 规范中的这组数据测试您的验签代码:

签名密钥 whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw
webhook-id msg_p5jXN8AQM9LWM0D4loKWxJek
webhook-timestamp 1614265330
请求体 {"test": 2432232314}
webhook-signature v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

测试时请跳过五分钟的时间检查:这个时间戳是 2021 年的。

推送来自固定的出口 IP。如果您的防火墙需要设置白名单,请向我们索取该地址。