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

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

نظام الـ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.

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

جسم كل طلب Webhook هو كائن 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://sign.wthaiq.com/s/uZ8..",
          "viewed_at": 1754000100,
          "signed_at": 1754499900,
          "identity": { "status": "approved", "provider": "didit", "level": "aes" },
          "fields": { "job_title": "مهندس برمجيات", "start_date": "2026-08-01" }
        }
      ],
      "ordered": true,
      "require_identity": true,
      "reference": "WTQ-000123",
      "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_ حيّ ويُطلق أحداثًا حقيقية بوضع livemode:true دائمًا، وأي طلب توقيع تنشئه يُرسل بريدًا فعليًا ويُفوتَر. للاختبار الآمن أنشئ طلبًا حقيقيًا صغيرًا واجعل نفسك الموقّع (بريدك الخاص) لتصلك أحداث 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.
• اجعل معالجتك idempotent بتخزين event.id وتجاهل المكرّر.
• ردّ 2xx بسرعة ثم عالِج العمل الثقيل بشكل غير متزامن.
• لا تفترض ترتيبًا؛ استعلِم عن أحدث حالة عبر الـAPI عند الحاجة إلى اليقين.
• خصّص سرًّا لكل نقطة استقبال واحفظه في متغيّر بيئة، وناوِبه دوريًّا.
• تذكّر أن كل حدث حيّ. حقل livemode ثابت على true دائمًا — لا يوجد وضع اختبار يُميَّز به الحدث.
• اشترك في ما تحتاجه فقط عبر enabled_events لتقليل الضجيج والحمل.
• راقب عمليات التسليم من اللوحة وأعد الإرسال عند اللزوم.
• استخدم HTTPS دائمًا ولا تكشف السرّ في السجلّات أو رسائل الخطأ.

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