Webhooks — دریافت رویدادهای امضا در زمان واقعی

قالب Payload

همه تحویل‌ها دارای یک schema JSON سطح بالا یکسان هستند: `event`، `data` و `timestamp`. نام رویداد نیز در هدر `X-Certyneo-Event` تکرار می‌شود، که امکان مسیریابی را قبل از parse کردن بدنه فراهم می‌کند. محتوای `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" }
    ],
    "fieldValues": [
      { "fieldId": "cm7x2k9p40005qz8h1a2b3c4d", "fieldType": "RADIO_GROUP", "recipientEmail": "alice@acme.com", "value": "Option B" }
    ],
    "signedDocumentUrl": "https://storage.certyneo.com/signed/cm7x2k9p4.../contrat.pdf?X-Amz-Expires=604800&X-Amz-Signature=..."
  },
  "timestamp": "2026-05-27T08:42:13.521Z"
}

signedDocumentUrl یک لینک از قبل امضا‌شده است که 7 روز از رویداد معتبر است: این از یک فراخوانی احراز هویت دوم برای دریافت PDF جلوگیری می‌کند. اگر امضا قبلی ناموفق بود یا روی پاکت QES تکمیل‌شده بدون سند ذخیره‌شده غایب است — null نیست؛ سپس مجدداً از GET /v1/envelopes/id/signed-document بروید، که منبع حقیقت باقی می‌ماند. همچنین به پخش دستی از dead-letter queue بیش از 7 روز بعد از رویداد توجه کنید: لینک payload منقضی است، endpoint API نه.

Payload با کدگذاری UTF-8 بدون BOM است. امضای HMAC بر روی بدنه خام همانطور که ارسال شده محاسبه می‌شود — فضاها را تغییر ندهید، تجزیه مجدد JSON اغلب ترتیب کلیدها را تغییر می‌دهد و تایید را شکست می‌دهد.

تایید امضای HMAC

هر درخواست با secret webhook شما امضا می‌شود (فقط یک‌بار در ایجاد subscription نمایش داده می‌شود). امضا در هدر `X-Certyneo-Signature` منتقل می‌شود: این HMAC-SHA256 بدنه خام درخواست است، به صورت هگزادسیمال کدگذاری‌شده، بدون پیشوند یا timestamp. قبل از پردازش payload، همیشه امضا را تأیید کنید — بدون این مرحله، هرکس می‌تواند یک رویداد جعلی بسازد و 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 شما خیلی طول بکشد در پاسخ دادن، اتصال را رد کند یا ۵xx (یا ۴۲۹) برگرداند، ما طبق عقبنشینی نمایی دوباره تلاش می‌کنیم: در مجموع ۵ تلاش، در حدود ۱ ساعت و ۲۰ دقیقه. پس از پنجمین تلاش، رویداد به صف dead-letter می‌رود — قابل مشاهده و قابل پخش مجدد از داشبورد شما، اما دیگر به طور خودکار تلاش نمی‌شود. رد صریح (۴۰۱، ۴۰۳، ۴۰۴، ۴۱۰، ۴۲۲…) هرگز دوباره تلاش نمی‌شود: پاسخ تغییر نخواهد کرد، رویداد مستقیماً به صف dead-letter می‌رود.

زمان‌های ذکرشده حداقل هستند: اسکن تلاش مجدد توسط یک cron کنترل می‌شود، بنابراین یک تلاش می‌تواند کمی بعد از زمان تئوری آغاز شود. رویدادهای متروک در Webhooks → شکست‌ها درج می‌شوند، با دکمه پخش مجدد دستی و بدون محدودیت مدت نگهداری. یک endpoint که پنج شکست قطعی را پیاپی تجربه کند — یا که ۴۰۴ / ۴۱۰ پاسخ دهد — به طور خودکار غیرفعال می‌شود، و شما از طریق ایمیل مطلع می‌شوید: پس از اصلاح، آن را دوباره فعال کنید، شمارنده از اول شروع می‌شود (هر تحویل موفق آن را نیز به صفر می‌رساند).

تست بدون ارسال پاکت واقعی

ابتدا یک subscription ایجاد کنید — پاسخ شامل `secret` مورد نیاز برای تأیید HMAC است، فقط یک‌بار نمایش داده می‌شود. از Settings → Webhooks، دکمه «Test» سپس یک POST امضا‌شده دقیقاً مانند یک تحویل واقعی ارسال می‌کند و پاسخ خام سرور شما را نمایش می‌دهد: این سریع‌ترین روش برای تأیید handler شما است، به‌طور محلی از طریق ngrok یا در continuous integration.

# 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 در هنگام ایجاد subscription توسط حفاظت SSRF رد می‌شود.

اشتراک‌ها مانند کلیدها بر اساس محیط جداشده‌اند: وبهوک ایجاد شده با کلید sk_test_ فقط رویدادهای پاکت‌های آزمایشی را دریافت می‌کند، وبهوک ایجاد شده با کلید sk_live_ فقط آنهایی از پاکت‌های واقعی را دریافت می‌کند. بنابراین یک پاکت آزمایشی هرگز به URL تولید شما نمی‌رسد، و هر بار بار‌اندازی نشان می‌دهد «sandbox» (true یا false).

برای اطلاعات بیشتر

• Hub توسعه‌دهندگان
• API امضای الکترونیکی
• ادغام‌های بومی
• صفحه امنیت
• طرح‌ها و قیمت‌گذاری