ويب هوكس تتلقى حوادث التوقيع في الوقت الحقيقي

شكل الحمولة

كل الحوادث بتشارك نفس المخطط JSON العلوي: `event`, `envelope_id`, `occurred_at`, `data`. محتويات `data` بتختلف حسب الحدث (حقول موثقة حسب الحدث في مرجع API). هنا مثال كامل `envelope.completed`.

{
  "event": "envelope.completed",
  "envelope_id": "env_01HG3K8X9Y2N4P5Q6R7S8T9V0W",
  "occurred_at": "2026-05-27T08:42:13.521Z",
  "data": {
    "title": "Contrat de prestation Acme Corp",
    "status": "completed",
    "created_at": "2026-05-24T14:12:00.000Z",
    "completed_at": "2026-05-27T08:42:13.000Z",
    "signers": [
      {
        "email": "client@acme.example",
        "name": "Alex Client",
        "signed_at": "2026-05-27T08:42:13.000Z",
        "method": "eidas_aes",
        "ip": "203.0.113.42"
      }
    ],
    "proof_pdf_url": "https://certyneo.com/api/envelopes/env_01HG.../proof.pdf"
  }
}

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

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

كل طلب بيتم توقيعه بسر webhook بتاعك (بيتم رؤيته مرة واحدة بس لما تخلق في لوحة التحكم، وبعدها بيتم تشفيره عند الراحة) ويتم نقل التوقيع في عنوان `Certyneo-Signature` بتنسيق `t=<timestamp>,v1=<hex_hmac>`. دائماً تحقق من التوقيع قبل معالجة الحمولة من غير هذه الخطوة، أي واحد ممكن يخلق حدث ويدعو نقطة النهاية.

import crypto from "node:crypto";

export function verifyCertyneoSignature(
  rawBody: string,
  signatureHeader: string,
  secret: string,
): boolean {
  // Header format: t=<timestamp>,v1=<hex_hmac>
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=")),
  );
  const ts = parts.t;
  const sig = parts.v1;
  if (!ts || !sig) return false;

  // Reject events older than 5 minutes (replay protection).
  const age = Math.abs(Date.now() / 1000 - Number(ts));
  if (age > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  // timingSafeEqual to mitigate timing attacks.
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(sig, "hex"),
  );
}

import hashlib
import hmac
import time


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

    Header format: `t=<timestamp>,v1=<hex_hmac>`
    Rejects events older than 5 minutes (replay protection).
    """
    parts = dict(p.split("=") for p in signature_header.split(","))
    ts = parts.get("t")
    sig = parts.get("v1")
    if not ts or not sig:
        return False

    if abs(time.time() - int(ts)) > 300:
        return False

    expected = hmac.new(
        secret.encode("utf-8"),
        f"{ts}.{raw_body.decode('utf-8')}".encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, sig)

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

لو الرد النهائي بتاعك غير HTTP 2xx (timeout, 5xx, connection refused) ، فانا بنترد على حساب الاحتياط التراكمي. مجموع 6 محاولات خلال 9 ساعات. بعد 6، بيكون الحدث علامة `failed` في لوحة المراقبة الخاصة بك ويتم ارسال رسالة تنبيه.

لو عايز تبعث حدث فاشل يدوياً، فإن لوحة التحكم في الويب هي بطانة إعادة تسليم لكل تسليم فاشل متاحة لمدة 7 أيام بعد الفشل النهائي.

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

نقطة النهاية `/v1/webhooks/test` بتقبل عنوان URL ونوع حدث، وتبيع حمولة وهمية موقعة تمامًا كحمولة حقيقية. مثالية للتحقق من صحة المتحكم الخاص بك في التكامل المستمر أو أثناء التطوير المحلي (مع ngrok أو ما شابه ذلك).

# Trigger a test webhook to your endpoint
curl -X POST https://api.certyneo.com/v1/webhooks/test \
  -H "Authorization: Bearer $CERTYNEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "envelope.completed", "url": "https://your.app/webhooks/certyneo"}'

علشان نروح اكتر

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