Everdeen Passport
العربية
ابدأ مجانًا

خطافات الويب

عندما يتغيّر شيء في بيانات شركتك، نرسل طلب 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 الخاصة به.

التحقق من التوقيع

لكل نقطة نهاية سرّ توقيع خاص بها يُعرض مرة واحدة عند إضافتها. تحقّق من كل طلب قبل التصرف بناءً عليه:

  1. اقرأ t (وقت Unix بالثواني) وv1 من الترويسة Evd-Signature.
  2. احسب HMAC-SHA256 بسرّك على t ثم نقطة ثم نص الطلب الخام كما وصل تمامًا.
  3. قارن النتيجة بـ v1 بمقارنة ثابتة الزمن.
  4. ارفض الطلب إذا ابتعد t عن ساعتك بأكثر من خمس دقائق.
  5. تخطَّ أي معرّف حدث سبق أن عالجته، ثم أرسل استجابة بحالة 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 أو إعادة التوجيه أو انتهاء المهلة محاولةً فاشلة. نعيد المحاولة حتى 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انتهت صلاحية شهادة.