Webhook
当贵公司的数据发生变化时,我们会向订阅该事件的每个端点发送 HTTPS 请求。请在控制台的“集成”中添加端点。
请求
POST | 通过 HTTPS 发送到您保存的端点 URL。不跟随重定向。 |
|---|---|
Content-Type | 请求正文是 JSON 格式的事件,说明见下文。 |
Evd-Signature | 请求的签名时间及其 HMAC-SHA256 签名。 |
负载
所有事件使用相同的外层结构。data 字段包含受影响的记录。
{
"event_id": "evt_8KQ2M4ZP7T",
"type": "passport.published",
"created_at": "2026-10-31T02:15:00Z",
"test": false,
"data": {
"product_id": "prd_5F3K9W",
"version": 3,
"state": "PUBLISHED",
"signature_id": "sig_2RT8LQ",
"resolver_url": "https://pass.everdeenone.com/01/09506000134352",
"published_at": "2026-10-31T02:15:00Z",
"withdrawn_at": null
}
}
| 字段 | 说明 |
|---|---|
event_id | 每个事件唯一。已处理过的 ID 请跳过。 |
type | 事件名称,见本页末尾的列表。 |
created_at | 事件发生的时间(UTC)。 |
test | 由测试密钥触发的事件为 true。 |
data | 受影响的记录,与其 GET 端点返回的内容相同。 |
验证签名
每个端点都有自己的签名密钥,仅在添加端点时显示一次。处理每个请求之前请先校验:
- 从 Evd-Signature 请求头中读取 t(Unix 时间,单位为秒)和 v1。
- 用您的密钥对 t、一个英文句点和原始请求正文(与收到的完全一致)计算 HMAC-SHA256。
- 以恒定时间比较方式将结果与 v1 比较。
- 如果 t 与您的时钟相差超过五分钟,请拒绝该请求。
- 跳过已处理过的事件 ID,然后返回 2xx 状态码。
import crypto from "node:crypto";
// rawBody: the request body as received (a Buffer), before JSON parsing.
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(
header.split(",").map((p) => [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]),
);
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.`)
.update(rawBody)
.digest();
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}import hashlib, hmac, time
# raw_body: the request body as received (bytes), before JSON parsing.
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t = parts.get("t", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(
secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256
).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))// rawBody: the request body as received, before JSON decoding.
func Verify(rawBody []byte, header, secret string) bool {
var t, v1 string
for _, p := range strings.Split(header, ",") {
k, v, _ := strings.Cut(p, "=")
switch k {
case "t":
t = v
case "v1":
v1 = v
}
}
ts, err := strconv.ParseInt(t, 10, 64)
if age := time.Now().Unix() - ts; err != nil || age > 300 || age < -300 {
return false
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(t + "."))
mac.Write(rawBody)
given, err := hex.DecodeString(v1)
return err == nil && hmac.Equal(given, mac.Sum(nil))
}import 'dart:convert';
import 'package:crypto/crypto.dart';
// rawBody: the request body as received, before JSON decoding.
bool verify(List<int> rawBody, String header, String secret) {
final parts = <String, String>{};
for (final p in header.split(',')) {
final i = p.indexOf('=');
if (i > 0) parts[p.substring(0, i)] = p.substring(i + 1);
}
final t = int.tryParse(parts['t'] ?? '');
final now = DateTime.now().millisecondsSinceEpoch ~/ 1000;
if (t == null || (now - t).abs() > 300) return false;
final mac = Hmac(sha256, utf8.encode(secret))
.convert([...utf8.encode('${parts['t']}.'), ...rawBody]);
final expected = mac.toString();
final given = parts['v1'] ?? '';
if (given.length != expected.length) return false;
var diff = 0;
for (var i = 0; i < given.length; i++) {
diff |= given.codeUnitAt(i) ^ expected.codeUnitAt(i);
}
return diff == 0;
}检查您的代码
使用下面的密钥、时间戳和正文,您的代码应计算出此 v1 值。
secret | example-secret |
|---|---|
t | 1767225600 |
body | {"event_id":"evt_8KQ2M4ZP7T","type":"passport.published"} |
v1 | 21cb13c5a2e80061c64fa3886778905d85dd5b87f2c5ceaa66d88b873dff5b40 |
重试与重新发送
请尽快响应,耗时的处理放在响应之后。非 2xx 响应、重定向或超时都算作一次失败。我们会在约 24 小时内最多重试 8 次,之后将该投递标记为失败。您可以在控制台或通过 API 重新发送任何投递。
事件
为每个端点选择要接收的事件。
| 事件 | 说明 |
|---|---|
product.created | 新增了产品。 |
product.updated | 产品信息已更改。 |
item.created | 产品新增了序列号或批次。 |
item.updated | 序列号或批次已更改。 |
item.published | 序列号或批次的护照已上线。 |
item.withdrawn | 序列号或批次已撤回。 |
compliance.created | 新增了证书或合规记录。 |
compliance.updated | 合规记录已更改。 |
document.uploaded | 已上传文件。 |
extraction.completed | 文件数据提取已完成。 |
review.required | 有更改等待审核。 |
review.approved | 审核员已批准更改。 |
review.rejected | 审核员已拒绝更改。 |
passport.published | 产品护照已发布。 |
passport.withdrawn | 产品护照已撤回。 |
certificate.expiring | 证书将在 30 天内到期。 |
certificate.expired | 证书已到期。 |