المطورين

Webhooks

احصل على أحداث التوقيع في الوقت الفعلي عبر HTTP من خلال عمليات التسليم الموقعة بواسطة HMAC، وإعادة المحاولة التلقائية، وشبكة أمان لإعادة التشغيل من وحدة التحكم.

HMAC

SHA-256 توقيع الطلب

Per-webhook سر، تم إرساله كـ X-Endorsed-Signature

10s

مهلة التسليم

قم بإرجاع 2xx داخل النافذة وإلا فشلت المحاولة

5×

إعادة المحاولة بعد المحاولة الأولى

60 ثانية، 5 م، 15 م، ساعة واحدة، ثم 6 ساعات

Replay

من وحدة تحكم المطور

افحص كل محاولة وأعد تشغيل الأحداث الفردية

ما يمكنك فعله بأحداث webhook

يُصدر كل انتقال مهم في دورة الحياة حدثًا مكتوبًا. استخدمها لتحديث السجلات الخاصة بك دون الاقتراع.

✅

تفعيل الإجراءات النهائية

عندما يتم توقيع المظروف بالكامل، قم بتحديث إدارة علاقات العملاء (CRM) الخاصة بك، أو قم بتحرير مورد متوفر، أو أرسل تأكيدًا داخل المنتج الخاص بك - كل ذلك دون استقصاء API.

🔄

مزامنة حالة المستند

حافظ على مزامنة قاعدة البيانات الخاصة بك مع دورة حياة التوقيع: تم الإرسال، الفتح، التوقيع، الرفض، انتهاء الصلاحية، الإبطال. حدث واحد لكل عملية انتقال، ولا يلزم وجود حلقة استقصاء.

📋

تسجيل التدقيق والامتثال

قم بإطعام الأحداث webhook في متجر التدقيق الخاص بك. تربط معرفات الارتباط كل حدث بطلب API الأصلي لإمكانية التتبع الكامل.

🔁

إعادة عمليات التسليم الفاشلة

الأحداث التي تستنفد سلم إعادة المحاولة تهبط في قائمة انتظار الحروف الميتة التي يمكنك فحصها في وحدة تحكم المطور وإعادة تشغيلها عمدًا.

Webhook مرجع الحدث

قم بتسجيل webhook، واختيار الأحداث التي تريدها، وسيقوم EndorsedSign بتسليم حمولة JSON مع `الحدث` و`معرف المستأجر` و`الطابع الزمني` و`البيانات`. تتطابق أسماء الأحداث مع السلاسل التي ترسلها في مكالمة الإنشاء webhook.

نوع الحدث عندما يشتعلحقول البيانات الرئيسية
document.created يمكنك تحميل مستند عبر APIمعرف المستند، معرف العميل، معرف المستند الخارجي
document.sentتم إرسال رابط التوقيع إلى المستلم الأولمعرف المستند، معرف العميل، القناة
document.viewedيفتح الموقع رابط التوقيعمعرف المستند، البريد الإلكتروني للموقع، تمت مشاهدته في
document.signed يُكمل الموقّع الفردي خطوتهمعرف المستند، البريد الإلكتروني الموقع، موقع في
document.completed جميع الأطراف وقعتمعرف المستند، مكتمل عند تنزيل Url
document.declined يرفض الموقع صراحةًمعرف المستند، البريد الإلكتروني للموقع، السبب
document.expired تصل الوثيقة إلى تاريخ انتهاء صلاحيتها بدون توقيعمعرف المستند، انتهت صلاحيته عند
signing.started يتم استرداد الرمز المميز لجلسة التوقيعمعرف المستند، معرف الجلسة، البريد الإلكتروني للموقع
signing.completed انتهاء جلسة التوقيع (تم التوقيع أو الرفض)معرف المستند، معرف الجلسة، النتيجة
customer.created / .updated / .deleted تقوم بتغيير سجل العميلمعرف العميل، معرف العميل الخارجي
template.created / .updated تقوم بتغيير القالبمعرف القالب، الاسم

القائمة الكاملة موجودة في الواجهة الخلفية "WEBHOOK_EVENTS". قم بإضافة الاشتراكات أو تضييق نطاقها لكل webhook — يقوم مسار التسليم بإرسال مكالمة HTTP واحدة لكل نقطة نهاية مسجلة.

التحقق من التوقيعات webhook (Node.js)

كل تسليم يتضمن رأس `X-Endorsed-Signature`: `t={unix_seconds},v1={hex}`. `v1` هو HMAC-SHA256 من `{timestamp}.{rawBody}` باستخدام السر الذي تم إرجاعه عند إنشاء webhook. رفض الطوابع الزمنية خارج ±5 دقائق. قد يستمر ظهور `X-Webhook-Signature` في عمليات تسليم اختبار بوابة المطور كاسم مستعار مهمل للنص فقط - تحقق من `X-Endorsed-Signature`. المتطلبات الأساسية: سر webhook الخاص بك في env var، وهو طريق سريع يحافظ على الجسم الخام. المخرجات المتوقعة: يتم رفض الحمولات غير المعترف بها أو التي تم العبث بها باستخدام 401 قبل تشغيل أي معالج.

typescript
import crypto from 'node:crypto';
import express from 'express';

const WEBHOOK_SECRET = process.env.ENDORSED_WEBHOOK_SECRET!;
const TOLERANCE_SECONDS = 5 * 60;

export function verifyWebhookSignature(
  rawBody: string,
  header: string | undefined,
  nowSeconds = Math.floor(Date.now() / 1000),
): boolean {
  if (!header) return false;
  let timestamp: number | null = null;
  let v1 = '';
  for (const part of header.split(',')) {
    const eq = part.indexOf('=');
    if (eq === -1) continue;
    const key = part.slice(0, eq).trim();
    const value = part.slice(eq + 1).trim();
    if (key === 't' && /^\d+$/.test(value)) timestamp = Number.parseInt(value, 10);
    if (key === 'v1' && /^[a-f0-9]{64}$/i.test(value)) v1 = value.toLowerCase();
  }
  if (timestamp === null || !v1) return false;
  if (Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) return false;
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(timestamp + '.' + rawBody)
    .digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(v1, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post(
  '/webhooks/endorsed',
  express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf.toString('utf8'); } }),
  (req, res) => {
    const sig = req.header('X-Endorsed-Signature');
    if (!verifyWebhookSignature((req as any).rawBody, sig)) {
      return res.status(401).send('Invalid signature');
    }
    res.sendStatus(200);
  },
);

قم بإرجاع 2xx خلال 30 ثانية أو تم وضع علامة على فشل التسليم. قم بإعادة المحاولة باستخدام السلم أعلاه للمحاولات الفاشلة وستظل قابلة لإعادة التشغيل من وحدة تحكم المطور.

كيفية إعداد نقطة نهاية webhook

  1. 1

    أنشئ نقطة النهاية في تطبيقك

    أضف مسارًا يقبل طلبات POST ويعيد HTTP 200 خلال 10 ثوانٍ. أي استجابة 2xx تعتبر بمثابة تسليم ناجح.

  2. 2

    قم بتسجيل نقطة النهاية في إعدادات المستأجر الخاص بك

    انتقل إلى المسؤول → الإعدادات → Webhooks. أدخل عنوان URL لنقطة النهاية الخاصة بك وحدد أنواع الأحداث التي تريدها. يتم إنشاء سر التوقيع لكل نقطة نهاية.

  3. 3

    التحقق من التوقيع على كل طلب

    اقرأ `X-Endorsed-Signature`. أعد حساب HMAC-SHA256 عبر `{timestamp}.{rawBody}` والوقت الثابت مقارنة بـ `v1` (انظر نموذج الكود أعلاه). ارفض رأسًا مفقودًا، أو قيمة سداسية عشرية سيئة، أو طابعًا زمنيًا خارج ±5 دقائق، أو عدم تطابق HMAC. `X-Webhook-Signature` هو اسم مستعار مهمل في بعض عمليات تسليم الاختبار - لا تعامله على أنه العقد المباشر.

  4. 4

    إرجاع 2xx بسرعة، ومعالجة غير متزامنة

    الإقرار بالتسليم بـ 200 خلال 10 ثوانٍ ووضع نص الحدث في قائمة الانتظار للمعالجة غير المتزامنة. تعرض وحدة تحكم المطور كل محاولة (الترويسات، النص، الحالة، التوقيت) وتتيح لك إعادة تشغيل أي تسليم - لا حاجة إلى إعادة تشغيل تدفق توقيع المصدر فقط لاختبار المعالج الخاص بك.

الأسئلة الشائعة

حمولة webhook حقيقية - اكتمل المستند

عندما تقوم جميع الأطراف بالتوقيع، EndorsedSign ينشر هذه الحمولة إلى نقطة النهاية المسجلة لديك. تحقق من توقيع HMAC، وقم بوضعه في قائمة الانتظار، ثم قم بالإقرار برقم 200.

سجل أحداث التسليم مع إدخالات دورة حياة المستند
سجل أحداث التسليم - أحداث دورة الحياة الموقعة مع الطوابع الزمنية ونتائج الحالة للتحقق من صحة التشغيل.

قم بتوصيل أول webhook

اطلب وضع الحماية، وسجل نقطة النهاية في المسؤول → المطور → Webhooks، وافحص أو أعد تشغيل كل عملية تسليم من وحدة تحكم المطور.