خطافات الويب
عندما يتغيّر شيء في بيانات شركتك، نرسل طلب 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 | فريد لكل حدث. تخطَّ أي معرّف سبق أن عالجته. |
type | اسم الحدث، من القائمة في آخر هذه الصفحة. |
created_at | وقت وقوع الحدث بالتوقيت العالمي المنسّق. |
test | تكون true عندما يتسبب مفتاح اختبار في الحدث. |
data | السجل المتأثر كما تُرجعه نقطة نهاية GET الخاصة به. |
التحقق من التوقيع
لكل نقطة نهاية سرّ توقيع خاص بها يُعرض مرة واحدة عند إضافتها. تحقّق من كل طلب قبل التصرف بناءً عليه:
- اقرأ t (وقت Unix بالثواني) وv1 من الترويسة Evd-Signature.
- احسب HMAC-SHA256 بسرّك على t ثم نقطة ثم نص الطلب الخام كما وصل تمامًا.
- قارن النتيجة بـ v1 بمقارنة ثابتة الزمن.
- ارفض الطلب إذا ابتعد t عن ساعتك بأكثر من خمس دقائق.
- تخطَّ أي معرّف حدث سبق أن عالجته، ثم أرسل استجابة بحالة 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 أو إعادة التوجيه أو انتهاء المهلة محاولةً فاشلة. نعيد المحاولة حتى 8 مرات خلال نحو 24 ساعة، ثم نضع على التسليم علامة فشل. يمكنك إعادة إرسال أي تسليم من لوحة التحكم أو عبر واجهة 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 | انتهت صلاحية شهادة. |