Webhook
使用 Webhook 就不必反复轮询。只要一票货上您可见的内容发生变化,我们就把事件推送到您提供的地址,通常在一分钟内送达。
- 向您的 Golden Arcus 对接人提供一个公网可访问的 https 地址,例如
https://erp.example.com/ga/webhooks。 - 我们会把该地址的签名密钥提供给您,以
whsec_开头。 - 开通后,您账号下的每个事件都会推送到该地址。
POST /ga/webhooks HTTP/1.1Host: erp.example.comContent-Type: application/jsonUser-Agent: GoldenArcus-Webhooks/1webhook-id: evt_e3-01JCX7M4Z9Q8R6T5V3W2Y1N0ABwebhook-timestamp: 1794521112webhook-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)) ); });}import base64import hashlibimport hmacimport time
def verify(secret: str, headers: dict, raw_body: bytes) -> bool: msg_id = headers["webhook-id"] timestamp = headers["webhook-timestamp"] if abs(time.time() - int(timestamp)) > 300: return False
key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + raw_body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
return any( hmac.compare_digest(part.split(",", 1)[1], expected) for part in headers["webhook-signature"].split(" ") if part.startswith("v1,") )function verify(string $secret, array $headers, string $rawBody): bool{ $id = $headers['webhook-id']; $timestamp = $headers['webhook-timestamp']; if (abs(time() - (int) $timestamp) > 300) { return false; }
$key = base64_decode(substr($secret, strlen('whsec_'))); $expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$rawBody", $key, true));
foreach (explode(' ', $headers['webhook-signature']) as $part) { [$version, $signature] = array_pad(explode(',', $part, 2), 2, ''); if ($version === 'v1' && hash_equals($expected, $signature)) { return true; } } return false;}import java.nio.charset.StandardCharsets;import java.security.MessageDigest;import java.util.Base64;import javax.crypto.Mac;import javax.crypto.spec.SecretKeySpec;
static boolean verify(String secret, String id, String timestamp, String signatureHeader, String rawBody) throws Exception { if (Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(timestamp)) > 300) return false;
byte[] key = Base64.getDecoder().decode(secret.substring("whsec_".length())); Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(key, "HmacSHA256")); byte[] signed = (id + "." + timestamp + "." + rawBody).getBytes(StandardCharsets.UTF_8); String expected = Base64.getEncoder().encodeToString(mac.doFinal(signed));
for (String part : signatureHeader.split(" ")) { if (part.startsWith("v1,") && MessageDigest.isEqual( part.substring(3).getBytes(StandardCharsets.UTF_8), expected.getBytes(StandardCharsets.UTF_8))) { return true; } } return false;}可以用 Standard Webhooks 规范中的这组数据测试您的验签代码:
| 签名密钥 | whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw |
webhook-id |
msg_p5jXN8AQM9LWM0D4loKWxJek |
webhook-timestamp |
1614265330 |
| 请求体 | {"test": 2432232314} |
webhook-signature |
v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= |
测试时请跳过五分钟的时间检查:这个时间戳是 2021 年的。
推送来源地址
Section titled “推送来源地址”推送来自固定的出口 IP。如果您的防火墙需要设置白名单,请向我们索取该地址。