التحقق من إشعارات Webhook
احتفظ ببايتات الاستدعاء الأصلية حتى يكتمل التحقق. يصل إشعار Webhook كاستدعاء من أنيس، وله ملف توقيع خاص به. توقيعه مختلف عن توقيع الردّ المرتبط باستدعائك.
الأجزاء الموقّعة
استخدم RFC 9421 والتسمية sig1 والخوارزمية ecdsa-p256-sha256 والوسم anis-partner-webhook-v1. اشترط الأجزاء التالية بهذا الترتيب تمامًا:
@method @target-uri content-digest webhook-id anis-webhook-attempt anis-application-idيوضح المثال التالي ملف التوقيع؛ موضع التوقيع التمثيلي ليس مثال اختبار قابلًا للتحقق.
Signature-Input: sig1=("@method" "@target-uri" "content-digest" "webhook-id" "anis-webhook-attempt" "anis-application-id");created=1792483200;expires=1792483500;keyid="partner-webhook-signing/0123456789abcdef0123456789abcdef";alg="ecdsa-p256-sha256";tag="anis-partner-webhook-v1"
Signature: sig1=:<base64 of the 64-byte P1363 signature>:تكون @method بالقيمة POST بأحرف كبيرة. وتمثّل @target-uri عنوان HTTPS الكامل المضبوط لديك، مع الاستعلام إن وُجد. أسماء الترويسات لا تتأثر بحالة الأحرف، لكن معرّفات الأجزاء في التوقيع بأحرف صغيرة. تكون Content-Digest بصيغة sha-256=:<standard base64 SHA-256 of the exact body bytes>:. تُربط أسطر نص التوقيع ببايت LF وبترميز UTF-8 دون LF في النهاية. التوقيع بصيغة P1363 الثابتة من 64 بايت، r ثم s، وبترميز base64 العادي، وليس DER أو base64url.
التحقق قبل التصرف
- اشترط Signature-Input وSignature، وتسمية توقيع واحدة فقط، والخوارزمية والوسم وقائمة الأجزاء المرتبة كما هي.
- احسب البصمة من المحتوى الأصلي قبل تحليل JSON أو إعادة تسلسله، واشترط تطابقها مع Content-Digest.
- اشترط العنوان الكامل المضبوط لديك ومعرّف تطبيقك وطريقة POST.
- افحص أوقات Unix بالثواني بساعة مضبوطة:
expires-created == 300وabs(now-created) <= 300وnow <= expires. لا توجد مهلة إضافية بعد الانتهاء. تُوقّع كل محاولة تسليم من جديد. - اجلب
/.well-known/partner-signing-keys.jsonعبر HTTPS من بيئة أنيس الخاصة بك. طابق kid كاملًا بوصفه اسمًا لا تفكّ محتواه، واشترطpurpose: "webhook"وحالة active أو next وnotBefore <= created. ارفض المفاتيح المُنهى استخدامها أو المخترقة وأي معرّف مطابق في revoked. وارفض وثيقة مفاتيح تحمل مادة مفتاح خاص. - أعد بناء نص التوقيع من الاستدعاء الفعلي ومعاملاته، وتحقق من التوقيع ذي
64بايت بالمفتاح العام. لا تثق بقائمة أجزاء مرسلة دون مقارنتها بالقائمة الثابتة. - بعد ذلك فقط، حلّل المحتوى واشترط تطابق id مع webhook-id وapplicationId مع anis-application-id، ثم عالج الإشعار المتحقق منه وامنع التكرار بمعرّفه.
تنشر وثيقة المفاتيح نفسها مفاتيح الردود بالقيمة purpose: "answer". وجود مفتاح في الوثيقة وحده لا يسمح باستخدامه للتحقق من الإشعارات. مفتاح الإشعارات منفصل عن مفتاح توقيع الردود. لا تطبق @status أو ;req أو حدّ حداثة الردود البالغ ستين ثانية على الإشعارات الواردة.
قبول الإشعار مرة واحدة
بعد التحقق، احفظ الإشعار بصورة دائمة وعالجه مرة واحدة. أعد حالة 2xx خلال عشر ثوانٍ. وإذا تكرر إشعار متحقق منه بالمعرّف نفسه، فأعد له 2xx أيضًا. لا تمنع تكرار استدعاء قبل التحقق منه، حتى لا يستطيع إشعار مزوّر حجب الإشعار الحقيقي.
تخضع رسالة التحقق للفحوص نفسها؛ لا تُعد قيمة التحدّي إلا بعد التحقق منه، كما يوضح دليل الإشعارات. وتخضع رسالة الاختبار أيضًا لهذا الملف. لا تنشئ أي منهما شراءً.
دعم SDK وأمثلة الاختبار
يتحقق الإصدار 2.2.0 من حزم SDK لـ .NET وNode.js وPHP وPython من الإشعارات، أما الإصدار 2.1.0 فلا يفعل. اتبع هذا الملف وأمثلة اختبار التوقيع المنشورة. يبقى التحقق من ردود API فحصًا مستقلًا.