شبكات الويب تتلقى أحداث التوقيع في الوقت الحقيقي

شكل الحمولة

تشترك جميع التسليمات في نفس مخطط JSON على المستوى الأعلى: `event`، `data` و `timestamp`. يتكرر اسم الحدث أيضاً في رأس `X-Certyneo-Event`، مما يسمح بالتوجيه قبل حتى معالجة الجسم. يختلف محتوى `data` حسب الحدث، لكنه يبقى دائماً كائن مسطح بقيم بسيطة — لا مصفوفة ولا كائن متداخل. إليك تسليم `envelope.completed` كامل.

POST /webhooks/certyneo HTTP/1.1
Host: your.app
Content-Type: application/json
X-Certyneo-Event: envelope.completed
X-Certyneo-Delivery-Id: cm8f2h6a10004qr9k5p2wm3xt
X-Certyneo-Signature: 4f3d1c8b2a9e7f60d5c4b3a2918e7f6d5c4b3a2918e7f6d5c4b3a2918e7f6d5c

{
  "id": "cm8f2h6a10004qr9k5p2wm3xt",
  "event": "envelope.completed",
  "data": {
    "envelopeId": "cm7x2k9p40001qz8h3f7bn2ld",
    "sandbox": false,
    "subject": "Contrat de prestation Acme Corp",
    "status": "COMPLETED",
    "signatureLevel": "ADVANCED",
    "aesSignerCount": 2,
    "completedAt": "2026-05-27T08:42:13.000Z",
    "recipientCount": 2,
    "recipients": [
      { "email": "alice@acme.com", "name": "Alice Martin", "role": "SIGNER", "status": "SIGNED" },
      { "email": "bob@acme.com", "name": "Bob Durand", "role": "SIGNER", "status": "SIGNED" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/cm7x2k9p4.../contrat.pdf?X-Amz-Expires=604800&X-Amz-Signature=..."
  },
  "timestamp": "2026-05-27T08:42:13.521Z"
}

هو رابط موقّع مسبقاً صالح لمدة 7 أيام من الحدث: يتجنب استدعاء مصرح ثانياً لاسترجاع ملف PDF. يكون غائباً — وليس فارغاً — إذا فشل التوقيع المسبق، أو على ظرف QES مكتمل بدون وثيقة مخزنة؛ عد إذاً إلى GET /v1/envelopes/id/signed-document، الذي يبقى مصدر الحقيقة. احذر أيضاً من إعادة التشغيل اليدوي من antitail queue أكثر من 7 أيام بعد الحدث: الرابط في الحمولة منتهي الصلاحية، endpoint API ليس كذلك.

يتم تشفير الحمولة بالرمز UTF-8 ، بدون BOM. يتم حساب توقيع HMAC على الجسم الخام كما تم إرساله لا تغير المساحات ، غالبًا ما يغير إعادة تحليل JSON ترتيب المفاتيح ويكسر التحقق.

تحقق من توقيع HMAC

يتم توقيع كل طلب برسك webhook (معروض مرة واحدة فقط عند إنشاء الاشتراك). يتم نقل التوقيع في رأس `X-Certyneo-Signature`: هو HMAC-SHA256 لجسم الطلب الخام، مشفر بصيغة hex، بدون بادئة أو طابع زمني. تحقق دائماً من التوقيع قبل معالجة الحمولة — بدون هذه الخطوة، يمكن لأي شخص أن يزيف حدثاً ويستدعي endpoint.

import crypto from "node:crypto";

export function verifyCertyneoSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  // X-Certyneo-Signature = HMAC-SHA256(secret, rawBody), hex-encoded.
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  const received = Buffer.from(signatureHeader, "hex");
  const computed = Buffer.from(expected, "hex");

  // timingSafeEqual throws when the two buffers differ in length —
  // a malformed header must return false, not crash the handler.
  if (received.length !== computed.length) return false;

  // timingSafeEqual to mitigate timing attacks.
  return crypto.timingSafeEqual(computed, received);
}

import hashlib
import hmac


def verify_certyneo_signature(
    raw_body: bytes, signature_header: str, secret: str
) -> bool:
    """Verify a Certyneo webhook signature.

    `X-Certyneo-Signature` holds the hex-encoded HMAC-SHA256 of the
    raw request body, computed with your webhook secret.
    """
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature_header)

سياسة إعادة التجربة

إذا استغرق endpoint الخاص بك وقتاً طويلاً للرد أو رفض الاتصال أو أرسل 5xx (أو 429)، فسنحاول مرة أخرى وفقاً لتراجع أسي: 5 محاولات إجمالية، على مدى حوالي 1 ساعة و 20 دقيقة. بعد الخمسة، ينتقل الحدث إلى قائمة الرسائل المرفوضة — يمكن الاطلاع عليها وإعادة تشغيلها من لوحة التحكم الخاصة بك، لكن لن تتم إعادة محاولة تلقائية. الرفض الصريح (401 أو 403 أو 404 أو 410 أو 422 إلخ) لن تتم إعادة محاولة له على الإطلاق: الرد لن يتغير، ينتقل الحدث مباشرة إلى قائمة الرسائل المرفوضة.

المهل الزمنية المذكورة هي الحد الأدنى: يتم مراقبة إعادة المحاولة بواسطة cron، لذا قد تنطلق محاولة بعد قليل من الوقت النظري. الأحداث المتخلى عنها مدرجة في Webhooks → الأخطاء، مع زر إعادة تشغيل يدوي بدون حد زمني للاحتفاظ. يتم تعطيل endpoint الذي يتعرض لخمسة أخطاء نهائية — أو يستجيب بـ 404 / 410 — تلقائياً، وستتلقى إشعاراً عبر البريد الإلكتروني: أعد تفعيله بعد الإصلاح، سيبدأ العداد من الصفر (أي تسليم ناجح يعيده أيضاً إلى الصفر).

اختبار دون إرسال مظروف حقيقي

أنشئ اشتراكاً أولاً — الرد يحتوي على `secret` الضروري للتحقق من HMAC، معروض مرة واحدة فقط. من Paramètres → Webhooks، يرسل زر « Tester » بعد ذلك POST موقّع تماماً مثل التسليم الفعلي ويعرض لك الرد الخام من خادمك: هذه أسرع طريقة للتحقق من معالج، محلياً عبر ngrok أو في التكامل المستمر.

# Create a subscription — "secret" is returned once, store it now.
curl -X POST https://api.certyneo.com/v1/webhooks \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your.app/webhooks/certyneo",
    "events": ["envelope.completed", "recipient.signed"]
  }'

يجب أن يكون عنوان URL قابل للوصول علناً في HTTPS: يتم رفض عنوان خاص أو localhost بواسطة حماية SSRF عند إنشاء الاشتراك.

الاشتراكات مقسمة حسب البيئة، مثل المفاتيح: webhook تم إنشاؤه باستخدام مفتاح sk_test_ يتلقى أحداث المغلفات الاختبارية فقط، webhook تم إنشاؤه باستخدام مفتاح sk_live_ يتلقى أحداث المغلفات الفعلية فقط. لذا فإن مغلف الاختبار لا يصل أبداً إلى عنوان الويب الخاص بك في الإنتاج، وتشير كل حمولة إلى "sandbox" (true أو false).

للذهاب إلى أبعد من ذلك

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