مصادقة التكامل وتوقيعات Webhook

الطلبات الواردة للتكامل

اضبط طريقة التكامل. يتطلب API_KEY ترويسة x-api-key بمفتاح نشط غير منتهٍ. يتطلب HMAC_SIGNATURE ترويستي x-signature وx-timestamp باستخدام سر التكامل.

يوقّع الحارس المفحوص timestamp + "." + نص JSON الأصلي بخوارزمية HMAC-SHA256 وناتج hex صغير دون بادئة sha256=. الوقت بثواني Unix ويُقبل فرق حتى 300 ثانية من ساعة الخادم. فحص الوقت لا يضمن منع تكرار الحدث.

مثال توقيع Node.js

حوّل البيانات لنص مرة واحدة ووقّع النص نفسه وأرسله دون إعادة تنسيق. وفّر الرابط والسر من إعدادات الخادم.

import { createHmac } from 'node:crypto';
const body = JSON.stringify({ event: 'example.event', data: { reference: 'TEST-1' } });
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = createHmac('sha256', process.env.INTEGRATION_SECRET)
  .update(timestamp + '.' + body).digest('hex');
const response = await fetch(process.env.INBOUND_WEBHOOK_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json',
    'x-timestamp': timestamp, 'x-signature': signature },
  body,
});
if (!response.ok) throw new Error('HTTP ' + response.status);

اسم الحدث توضيحي؛ اختر حدثاً يدعمه التكامل والسير. انسخ رابط الوارد الفعلي من الإعداد. مسار الموجّه المفحوص /api/v1/webhooks/:businessId/:integrationType/inbound.

التحقق من الصادر

عند إعداد سر Webhook تستخدم خدمة تسليم التكامل المفحوصة الترويستين والطريقة نفسيهما لكن بسر Webhook لا سر التكامل الوارد. التقط نص الطلب قبل التحليل واحسب الناتج وقارنه بدالة ثابتة الزمن بعد فحص تساوي طول البايتات. طبّق سماحية الوقت وتعامل مع الأثر المكرر. دون سر مهيأ لا تعتبر الطلب موقّعاً.

سلوك التسليم والأخطاء

تستخدم الخدمة المفحوصة مهلة HTTP قدرها 10 ثوانٍ وثلاث إعادات افتراضية بعد أخطاء النقل المرمية بتأخير 1 و5 و15 ثانية. تُسجّل استجابات HTTP غير الناجحة كأخطاء لكنها لا ترمي خطأ لإعادة المحاولة بذاتها. قد تختلف المسارات والإصدارات؛ اختبر مسارك وافحص السجلات ولا تعد بتسليم مضمون.

تؤدي البيانات الناقصة أو الخاطئة أو الوقت المنتهي إلى أخطاء مصادقة، وقد يؤدي التكامل الغائب أو غير النشط للمنع. زامن الساعات وحافظ على البايتات وحدد سر كل اتجاه.