Webhook
Khi dữ liệu của công ty bạn thay đổi, chúng tôi gửi một yêu cầu HTTPS đến mọi điểm cuối đăng ký sự kiện đó. Thêm điểm cuối trong bảng điều khiển, mục Tích hợp.
Yêu cầu
POST | Gửi qua HTTPS đến URL điểm cuối bạn đã lưu. Không theo chuyển hướng. |
|---|---|
Content-Type | Nội dung là sự kiện ở dạng JSON, mô tả bên dưới. |
Evd-Signature | Thời điểm ký yêu cầu và chữ ký HMAC-SHA256 của nó. |
Nội dung
Mọi sự kiện dùng cùng một cấu trúc. Trường data chứa bản ghi bị ảnh hưởng.
{
"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
}
}
| Trường | Mô tả |
|---|---|
event_id | Duy nhất cho mỗi sự kiện. Bỏ qua ID bạn đã xử lý. |
type | Tên sự kiện, theo danh sách ở cuối trang này. |
created_at | Thời điểm xảy ra sự kiện, theo giờ UTC. |
test | Là true khi sự kiện do khóa thử nghiệm gây ra. |
data | Bản ghi bị ảnh hưởng, giống như điểm cuối GET của nó trả về. |
Xác minh chữ ký
Mỗi điểm cuối có khóa bí mật ký riêng, chỉ hiển thị một lần khi bạn thêm điểm cuối. Kiểm tra mọi yêu cầu trước khi xử lý:
- Đọc t (giờ Unix tính bằng giây) và v1 từ tiêu đề Evd-Signature.
- Tính HMAC-SHA256 bằng khóa bí mật của bạn trên t, một dấu chấm và nội dung yêu cầu gốc, đúng như khi nhận.
- So sánh kết quả với v1 theo thời gian không đổi.
- Từ chối yêu cầu nếu t lệch quá năm phút so với đồng hồ của bạn.
- Bỏ qua ID sự kiện đã xử lý, sau đó phản hồi bằng mã trạng thái 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;
}Kiểm tra mã của bạn
Với khóa bí mật, dấu thời gian và nội dung này, mã của bạn phải tính ra giá trị v1 này.
secret | example-secret |
|---|---|
t | 1767225600 |
body | {"event_id":"evt_8KQ2M4ZP7T","type":"passport.published"} |
v1 | 21cb13c5a2e80061c64fa3886778905d85dd5b87f2c5ceaa66d88b873dff5b40 |
Thử lại và gửi lại
Hãy phản hồi nhanh và xử lý công việc chậm sau đó. Phản hồi ngoài 2xx, chuyển hướng hoặc hết thời gian chờ đều tính là một lần thất bại. Chúng tôi thử lại tối đa 8 lần trong khoảng 24 giờ, sau đó đánh dấu lần gửi là thất bại. Bạn có thể gửi lại bất kỳ lần gửi nào từ bảng điều khiển hoặc API.
Sự kiện
Chọn những sự kiện mà mỗi điểm cuối nhận.
| Sự kiện | Mô tả |
|---|---|
product.created | Một sản phẩm đã được thêm. |
product.updated | Thông tin sản phẩm đã thay đổi. |
item.created | Một số sê-ri hoặc lô đã được thêm vào sản phẩm. |
item.updated | Một số sê-ri hoặc lô đã thay đổi. |
item.published | Hộ chiếu của một số sê-ri hoặc lô đã hoạt động. |
item.withdrawn | Một số sê-ri hoặc lô đã bị thu hồi. |
compliance.created | Một chứng nhận hoặc hồ sơ tuân thủ đã được thêm. |
compliance.updated | Một hồ sơ tuân thủ đã thay đổi. |
document.uploaded | Một tài liệu đã được tải lên. |
extraction.completed | Đã trích xuất xong dữ liệu từ tài liệu. |
review.required | Một thay đổi đang chờ xem xét. |
review.approved | Người duyệt đã chấp thuận một thay đổi. |
review.rejected | Người duyệt đã từ chối một thay đổi. |
passport.published | Hộ chiếu sản phẩm đã được xuất bản. |
passport.withdrawn | Hộ chiếu sản phẩm đã bị thu hồi. |
certificate.expiring | Một chứng nhận sẽ hết hạn trong vòng 30 ngày. |
certificate.expired | Một chứng nhận đã hết hạn. |