Webhooks — إشعارات لحظية بحالة كل توقيع.

أربع خطوات من الحدث إلى ردّ خادمك

نظام إشعارات الأحداث في «وثائق» بسيط ومتين: تُسجّل عنوانًا واحدًا يستقبل الأحداث التي تهمّك، ونتولّى نحن إرسالها إليه موقَّعةً كلّما تغيّر شيء. فلا حاجة إلى الاستطلاع الدوري (polling) ولا إلى الاستعلام المتكرّر، إذ يصلك الحدث فور وقوعه.

curl -X POST https://wthaiq.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.com/hooks/wthaiq",
    "enabled_events": ["signature_request.completed", "signer.signed"]
  }'

{
  "id": "we_1a",
  "object": "webhook_endpoint",
  "url": "https://api.acme.com/hooks/wthaiq",
  "enabled_events": ["signature_request.completed", "signer.signed"],
  "status": "enabled",
  "secret": "whsec_7bK2c8Vd1QpN9sR4tHmZ0xY",   // يظهر مرّة واحدة — احفظه بأمان
  "created_at": 1754000000
}

POST /hooks/wthaiq HTTP/1.1
Host: api.acme.com
Content-Type: application/json
Wthaiq-Version: 2026-07-01
Wthaiq-Signature: t=1754500000,v1=6ff7d3f2b1a0c9e4d5f8a1b0c3a...

{"id":"evt_2M8kQ1","object":"event","type":"signature_request.completed", ... }

جميع أنواع الأحداث ومتى تُطلق

تنقسم الأحداث إلى مجموعات: أحداث على مستوى طلب التوقيع signature_request.*، وأحداث خاصة بكل موقّع signer.*، إلى جانب أحداث ختم المستند والتحقّق العام. اشترك في ما تحتاجه فقط عبر enabled_events.

غلاف الحدث والكائن المتأثّر

جسم كل إشعار يصلك هو كائن event موحَّد البنية يضمّ الكائن المتأثّر في data.object. ويدلّ الحقل type على نوع الحدث، و livemode يميّز الوضع الحيّ عن الاختبار، و created_at طابع زمني بصيغة Unix بالثواني.

{
  "id": "evt_...",
  "object": "event",
  "type": "signature_request.completed",
  "created_at": 1754500000,
  "livemode": true,
  "data": {
    "object": { /* الكائن المتأثّر: signature_request أو signer أو … */ }
  }
}

{
  "id": "evt_2M8kQ1",
  "object": "event",
  "type": "signature_request.completed",
  "created_at": 1754500000,
  "livemode": true,
  "data": {
    "object": {
      "id": "sr_3n8Kd2Qa1V",
      "object": "signature_request",
      "livemode": true,
      "status": "completed",
      "title": "عقد عمل — أحمد م.",
      "legal_level": "aes",
      "format": "pades-lt",
      "source": { "type": "template", "template_id": "tpl_employment" },
      "signers": [
        {
          "id": "sgr_9fA2",
          "object": "signer",
          "name": "أحمد محمد",
          "email": "ahmed@example.com",
          "type": "individual",
          "method": "draw",
          "require_identity": true,
          "order": 1,
          "status": "signed",
          "signing_url": "https://wthaiq.com/sign.php?token=uZ8..",
          "viewed_at": 1754000100,
          "signed_at": 1754499900,
          "identity": { "status": "approved", "provider": "external", "level": "aes" },
          "fields": { "job_title": "مهندس برمجيات", "start_date": "2026-08-01" }
        }
      ],
      "ordered": true,
      "require_identity": true,
      "reference": "WTQ-1A2B3C4D5E6F",
      "reminders": { "enabled": true, "interval_hours": 48, "max": 3 },
      "expires_at": 1755000000,
      "completed_at": 1754500000,
      "download_url": "https://wthaiq.com/api/v1/signature_requests/sr_3n8Kd2Qa1V/download",
      "metadata": { "order_id": "A-1024" },
      "created_at": 1754000000
    }
  }
}

تحقّق من كل طلب قبل الوثوق به

ترسل «وثائق» مع كل طلب ترويسة Wthaiq-Signature تتيح لك التأكّد من أن الحمولة صادرة منّا وأنه لم يُعبَث بها. والتحقّق إلزامي: لا تعالِج أي حمولة قبل نجاحه.

خطوات التحقّق

تنفيذ التحقّق

const express = require('express');
const crypto  = require('crypto');
const app = express();

const SECRET = process.env.WTHAIQ_WEBHOOK_SECRET; // whsec_...
const TOLERANCE = 300; // ثوانٍ

// مهم: استقبل الجسم الخام (Buffer)، لا JSON المُحلَّل
app.post('/hooks/wthaiq',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const raw    = req.body;                       // Buffer خام
    const header = req.get('Wthaiq-Signature') || '';

    // 1) استخرج t و v1
    const parts = Object.fromEntries(
      header.split(',').map(p => p.split('=')));
    const t = parts.t, v1 = parts.v1;

    // 2) نافذة الطابع الزمني (5 دقائق)
    const now = Math.floor(Date.now() / 1000);
    if (!t || Math.abs(now - Number(t)) > TOLERANCE)
      return res.status(400).send('timestamp out of tolerance');

    // 3) أعد حساب HMAC على "{t}.{raw_body}"
    const signedPayload = t + '.' + raw.toString('utf8');
    const expected = crypto
      .createHmac('sha256', SECRET)
      .update(signedPayload)
      .digest('hex');

    // 4) مقارنة ثابتة الزمن
    const ok = v1 && expected.length === v1.length &&
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
    if (!ok) return res.status(400).send('invalid signature');

    const event = JSON.parse(raw.toString('utf8'));
    // أزل التكرار على event.id، ثم ردّ فورًا وعالِج لاحقًا
    res.status(200).send('ok');
  });

import hmac, hashlib, time, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["WTHAIQ_WEBHOOK_SECRET"].encode()  # whsec_... كبايتات
TOLERANCE = 300  # ثوانٍ

@app.post("/hooks/wthaiq")
def handle():
    raw = request.get_data()               # بايتات خام — لا تستخدم request.json
    header = request.headers.get("Wthaiq-Signature", "")

    # 1) استخرج t و v1
    parts = dict(kv.split("=", 1) for kv in header.split(",") if "=" in kv)
    t, v1 = parts.get("t"), parts.get("v1")

    # 2) نافذة الطابع الزمني (5 دقائق)
    if not t or abs(time.time() - int(t)) > TOLERANCE:
        abort(400)

    # 3) أعد حساب HMAC على "{t}.{raw_body}"
    signed_payload = f"{t}.".encode() + raw
    expected = hmac.new(SECRET, signed_payload, hashlib.sha256).hexdigest()

    # 4) مقارنة ثابتة الزمن
    if not v1 or not hmac.compare_digest(expected, v1):
        abort(400)

    event = request.get_json()
    # أزل التكرار على event["id"]، ثم ردّ فورًا وعالِج لاحقًا
    return "", 200

<?php
$secret = getenv('WTHAIQ_WEBHOOK_SECRET');   // whsec_...
$tolerance = 300;                           // ثوانٍ

// اقرأ الجسم الخام — لا تستخدم $_POST مطلقًا
$raw    = file_get_contents('php://input');
$header = $_SERVER['HTTP_WTHAIQ_SIGNATURE'] ?? '';

// 1) استخرج t و v1
$parts = [];
foreach (explode(',', $header) as $kv) {
    [$k, $v] = array_pad(explode('=', $kv, 2), 2, '');
    $parts[$k] = $v;
}
$t  = $parts['t']  ?? '';
$v1 = $parts['v1'] ?? '';

// 2) نافذة الطابع الزمني (5 دقائق)
if ($t === '' || abs(time() - (int)$t) > $tolerance) {
    http_response_code(400);
    exit('timestamp out of tolerance');
}

// 3) أعد حساب HMAC على "{t}.{raw_body}"
$signedPayload = $t . '.' . $raw;
$expected = hash_hmac('sha256', $signedPayload, $secret);

// 4) مقارنة ثابتة الزمن
if ($v1 === '' || !hash_equals($expected, $v1)) {
    http_response_code(400);
    exit('invalid signature');
}

$event = json_decode($raw, true);
// أزل التكرار على $event['id']، ثم ردّ فورًا وعالِج لاحقًا
http_response_code(200);
echo 'ok';

ماذا يحدث عند الفشل، وكيف تبني معالجًا متينًا

اختبر تكاملك قبل الإطلاق

ابنِ تكاملك بمفتاح تجربة sk_test_؛ فأحداثه تحمل livemode:false ولا يُخصم به شيء ولا تُرسَل به رسالة إلى أحد. وسجّل نقطة الاستقبال بالمفتاح التجريبي نفسه عبر POST /v1/webhook_endpoints لتصلها أحداث التجربة، فالنقاط المضافة من لوحة المطوّرين حيّة. ثم أنشئ طلبًا تجريبيًّا ببريدك وافتح رابط التوقيع بنفسك، لتصلك أحداث signature_request.* و signer.* إلى نقطة استقبالك دون التأثير على عملاء حقيقيين.

# أنشئ طلبًا حقيقيًا صغيرًا (استخدم بريدك كمستلم) لتوليد أحداث حقيقية — يُحتسب إرسالًا من رصيد باقتك
curl -X POST https://wthaiq.com/api/v1/signature_requests \
  -H "Authorization: Bearer sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Wthaiq-Version: 2026-07-01" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "اختبار Webhook",
    "source": {"type":"template","template_id":"tpl_employment"},
    "legal_level": "ses",
    "signers": [{"name":"مطوّر","email":"you@example.com","method":"draw"}]
  }'

قائمة تحقّق الإنتاج

• تحقّق من كل طلب قبل معالجته؛ لا تثق بأي حمولة غير موقّعة أو خارج نافذة الطابع الزمني.
• استخدم الجسم الخام حرفيًّا في حساب HMAC، قبل أي تحليل JSON.
• اجعل معالجتك لا تتأثّر بالتكرار بتخزين event.id وتجاهل المكرّر.
• ردّ 2xx بسرعة ثم أنجز العمل الثقيل في مهمّة غير متزامنة.
• لا تفترض ترتيبًا؛ واستعلِم عن أحدث حالة عبر واجهة برمجة التطبيقات إذا احتجت إلى التيقّن منها.
• خصّص سرًّا لكل نقطة استقبال واحفظه في متغيّر بيئة، واستبدله دوريًّا.
• افصل أحداث التجربة عن الحيّة. حقل livemode يساوي false في أحداث مفاتيح التجربة؛ فلا تُنفّذ عليها أثرًا حقيقيًّا في نظامك.
• اشترك في ما تحتاجه فقط عبر enabled_events لتقليل الضجيج والحمل.
• راقب عمليات التسليم من لوحة المطوّرين، وأعد الإرسال عند اللزوم.
• استخدم HTTPS دائمًا ولا تكشف السرّ في السجلّات أو رسائل الخطأ.

أسئلة المطوّرين حول الـWebhooks