Everdeen Passport
简体中文
免费开始

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 端点返回的内容相同。

验证签名

每个端点都有自己的签名密钥,仅在添加端点时显示一次。处理每个请求之前请先校验:

  1. 从 Evd-Signature 请求头中读取 t(Unix 时间,单位为秒)和 v1。
  2. 用您的密钥对 t、一个英文句点和原始请求正文(与收到的完全一致)计算 HMAC-SHA256。
  3. 以恒定时间比较方式将结果与 v1 比较。
  4. 如果 t 与您的时钟相差超过五分钟,请拒绝该请求。
  5. 跳过已处理过的事件 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 值。

secretexample-secret
t1767225600
body{"event_id":"evt_8KQ2M4ZP7T","type":"passport.published"}
v121cb13c5a2e80061c64fa3886778905d85dd5b87f2c5ceaa66d88b873dff5b40

重试与重新发送

请尽快响应,耗时的处理放在响应之后。非 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证书已到期。