> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# الويب هوكس

> تلقي إشعارات HTTP في الوقت الفعلي عند وقوع أحداث في مستأجر Truthlocks الخاص بك.

تتيح الويب هوكس لتطبيقك تلقي إشعارات تلقائية عند وقوع أحداث في حسابك على Truthlocks — على سبيل المثال، عند سك شهادة، أو تدوير مفتاح، أو فشل التحقق. بدلاً من استقصاء واجهة برمجة التطبيقات عن التغييرات، يتلقى خادمك طلب HTTP POST مع تفاصيل الحدث.

## كيف يعمل

**1. تسجيل نقطة نهاية**

أضف نقطة نهاية لخطاف الويب في **الإعدادات > خطافات الويب** في [وحدة تحكم المستأجر](https://console.truthlocks.com). قم بتوفير عنوان URL HTTPS يمكن الوصول إليه علنًا واختر أنواع الأحداث التي ترغب في تلقيها.

**2. تلقي الأحداث**

عند حدوث حدث مطابق، يرسل Truthlocks طلب HTTP POST إلى عنوان URL الخاص بك مع حمولة JSON تصف الحدث.

**3. التحقق من التوقيع**

يتضمن كل طلب توقيع HMAC-SHA256 في رأس `X-Truthlocks-Signature`. تحقق منه باستخدام سر نقطة النهاية لتأكيد أن الطلب جاء من Truthlocks.

**4. الاستجابة بـ 200**

أرجع رمز حالة HTTP `200` للإقرار بالاستلام. إذا فشل نقطة النهاية الخاصة بك أو انتهت مهلتها، فإن Truthlocks تعيد المحاولة مع تراجع أسي.

## أنواع الأحداث

يتم تجميع الأحداث في فئات. يمكنك الاشتراك في أحداث فردية أو استخدام حرف بدل (`attestation.*`) لتلقي جميع الأحداث في فئة.

| الفئة | الحدث | المشغل |
| :- | :- | :- |
| **الشهادات** | `attestation.created` | يتم سك شهادة جديدة |
| | `attestation.revoked` | تم إلغاء شهادة |
| | `attestation.expired` | وصلت شهادة إلى تاريخ انتهائها |
| | `attestation.superseded` | تم استبدال شهادة بإصدار أحدث |
| **التحقق** | `verification.completed` | نجاح فحص التحقق |
| | `verification.failed` | فشل فحص التحقق |
| **المصدرون** | `issuer.created` | يتم تسجيل مصدر جديد |
| | `issuer.updated` | تغير ملف تعريف جهة إصدار أو إعداداتها |
| | `issuer.suspended` | تم تعليق جهة إصدار |
| **المفاتيح** | `key.created` | يتم تسجيل مفتاح توقيع |
| | `key.rotated` | تم تدوير مفتاح توقيع |
| | `key.revoked` | تم إلغاء مفتاح توقيع |
| | `key.compromised` | تم الإبلاغ عن مفتاح على أنه مخترق |
| **الفريق** | `team.member_invited` | يتم إرسال دعوة فريق |
| | `team.member_joined` | يقبل عضو الفريق دعوة |
| | `team.member_removed` | تم إزالة عضو فريق |
| | `team.role_changed` | تم تحديث دور عضو فريق |
| **الفوترة** | `billing.subscription.created` | يتم إنشاء اشتراك جديد |
| | `billing.subscription.updated` | تم تعديل اشتراك |
| | `billing.invoice.created` | تم إنشاء فاتورة جديدة |
| | `billing.usage.threshold` | تم الوصول إلى عتبة الاستخدام |
| **المستهلك** | `consumer.content.protected` | يحمي المستهلك محتوى جديدًا |
| **إشارات المخاطر** | `risk.signal.created` | يتم استيعاب إشارة مخاطر (أي مسار اكتشاف) |
| | `risk.signal.escalated` | تجاوزت درجة إشارة المخاطر عتبة المراجعة التلقائية |
| **الإيصالات** | `receipt.created` | يتم سك إيصال جديد |
| | `receipt.revoked` | تم إلغاء إيصال |
| | `receipt.type.created` | تم إنشاء نوع إيصال جديد |
| | `receipt.type.deprecated` | تم إهمال نوع إيصال |
| **الأمان** | `security.password_changed` | يغير المستخدم كلمة مروره |
| | `security.api_key_compromised` | تم وضع علامة على مفتاح API على أنه مخترق |
| | `security.suspicious_activity` | تم اكتشاف نشاط حساب مشبوه |

### فلاتر الأحرف البديلة

استخدم `category.*` للاشتراك في كل حدث في فئة. على سبيل المثال، `attestation.*` يطابق `attestation.created` و`attestation.revoked` و`attestation.expired` و`attestation.superseded`.

## حدود نقطة النهاية حسب الخطة

يعتمد عدد نقاط نهاية الويب هوك التي يمكنك إنشاؤها على مستوى خطتك:

| الخطة | حد نقطة النهاية |
| :- | :- |
| مجاني | 1 |
| المبتدئ | 3 |
| الأعمال | 10 |
| المؤسسة | 25 |

هل تحتاج إلى المزيد من نقاط النهاية؟ اتصل بمدير حسابك أو قم بترقية خطتك في **الإعدادات > الفواتير**.

## إنشاء نقطة نهاية

1. في لوحة تحكم المستأجر، انتقل إلى **الإعدادات > Webhooks**.
2. انقر على **إضافة نقطة نهاية**.
3. أدخل اسمًا، وعنوان URL لوجهة HTTPS الخاص بك، وحدد أنواع الأحداث التي ترغب في تلقيها.
4. انقر فوق **إنشاء**.

تعرض وحدة التحكم سر نقطة النهاية الخاص بك مرة واحدة. انسخه فورًا — لا يمكنك استعادته لاحقًا.

### عبر واجهة برمجة التطبيقات

```http Request theme={null}
POST /v1/webhooks/endpoints
X-API-Key: tl_live_...
Content-Type: application/json

{
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "event_filters": ["attestation.*", "verification.completed"]
}
```

```json Response theme={null}
{
  "id": "ep_abc123",
  "name": "My Backend",
  "url": "https://api.example.com/webhooks/truthlock",
  "status": "active",
  "secret": "whsec_...",
  "event_filters": ["attestation.*", "verification.completed"],
  "created_at": "2026-03-25T12:00:00Z"
}
```

### نقاط نهاية القائمة

استرداد جميع نقاط نهاية webhook لمستأجرك:

```http Request theme={null}
GET /v1/webhooks/endpoints
X-API-Key: tl_live_...
```

راجع [مرجع API](https://docs.truthlocks.com/ar/api-reference/webhooks/list-endpoints.md) الكامل للحصول على تفاصيل الاستجابة.

## التحقق من التوقيعات

يتضمن كل طلب ويب هوك رأس توقيع للتحقق. تحقق دائمًا من التوقيعات قبل معالجة الأحداث.

**تنسيق التوقيع:**

```
X-Truthlocks-Signature: t=1710000000,v1=a1b2c3d4e5f6...
```

حيث `t` هو الطابع الزمني لـ Unix و `v1` هو ملخص HMAC-SHA256 السداسي العشري.

**خطوات التحقق:**

1. استخرج `t` (الطابع الزمني) و `v1` (التوقيع) من الرأس.
2. ارفض الطلب إذا كان الطابع الزمني أقدم من 5 دقائق.
3. قم بدمج `{timestamp}.{raw_request_body}` لتشكيل سلسلة التوقيع.
4. احسب HMAC-SHA256 لسلسلة التوقيع باستخدام سر نقطة النهاية الخاصة بك.
5. قارن الملخص المحسوب بـ `v1` باستخدام مقارنة ثابتة الوقت.

```typescript verify-webhook.ts theme={null}
import crypto from "crypto";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/truthlock", (req, res) => {
  const sigHeader = req.headers["x-truthlocks-signature"] as string;
  if (!sigHeader) return res.status(401).send("Missing signature");

  const parts = Object.fromEntries(
    sigHeader.split(",").map((p) => p.split("=") as [string, string])
  );
  const timestamp = parts["t"];
  const signature = parts["v1"];

  // Reject stale requests (5-minute window)
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) return res.status(401).send("Timestamp expired");

  // Compute expected signature
  const signingString = `${timestamp}.${req.body.toString()}`;
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(signingString)
    .digest("hex");

  // Constant-time comparison
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body.toString());
  console.log("Received event:", event.type);

  res.status(200).json({ received: true });
});
```

```go verify-webhook.go theme={null}
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"fmt"
	"io"
	"math"
	"net/http"
	"strconv"
	"strings"
	"time"
)

func verifyWebhook(r *http.Request, secret string) ([]byte, error) {
	sig := r.Header.Get("X-Truthlocks-Signature")
	if sig == "" {
		return nil, fmt.Errorf("missing signature header")
	}

	parts := map[string]string{}
	for _, p := range strings.Split(sig, ",") {
		kv := strings.SplitN(p, "=", 2)
		if len(kv) == 2 {
			parts[kv[0]] = kv[1]
		}
	}

	ts, _ := strconv.ParseInt(parts["t"], 10, 64)
	age := math.Abs(float64(time.Now().Unix() - ts))
	if age > 300 {
		return nil, fmt.Errorf("timestamp expired")
	}

	body, err := io.ReadAll(r.Body)
	if err != nil {
		return nil, err
	}

	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(fmt.Sprintf("%d.%s", ts, body)))
	expected := hex.EncodeToString(mac.Sum(nil))

	if !hmac.Equal([]byte(parts["v1"]), []byte(expected)) {
		return nil, fmt.Errorf("invalid signature")
	}

	return body, nil
}
```

```python verify_webhook.py theme={null}
import hashlib
import hmac
import time
from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/webhooks/truthlock", methods=["POST"])
def handle_webhook():
    sig_header = request.headers.get("X-Truthlocks-Signature", "")
    parts = dict(p.split("=", 1) for p in sig_header.split(","))

    timestamp = parts.get("t", "")
    signature = parts.get("v1", "")

    # Reject stale requests
    if abs(time.time() - int(timestamp)) > 300:
        abort(401, "Timestamp expired")

    # Compute expected signature
    signing_string = f"{timestamp}.{request.get_data(as_text=True)}"
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        signing_string.encode(),
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        abort(401, "Invalid signature")

    event = request.get_json()
    print(f"Received event: {event['type']}")
    return {"received": True}
```

> [!WARNING]
>
> استخدم دائمًا دالة مقارنة ثابتة الوقت (مثل `crypto.timingSafeEqual` أو `hmac.compare_digest`) لمنع هجمات التوقيت.

## رؤوس الطلب

يتضمن كل تسليم ويب هوك هذه الرؤوس:

| الرأس | الوصف |
| :- | :- |
| `Content-Type` | `application/json` |
| `User-Agent` | `Truthlocks-Webhook-Service/1.0` |
| `X-Truthlocks-Event-Id` | معرف فريد للحدث |
| `X-Truthlocks-Event-Type` | نوع الحدث (على سبيل المثال، `attestation.created`) |
| `X-Truthlocks-Timestamp` | طابع زمني Unix لمحاولة التسليم |
| `X-Truthlocks-Signature` | توقيع HMAC-SHA256 للتحقق |

## سلوك إعادة المحاولة

إذا أعادت نقطة النهاية الخاصة بك رمز حالة غير 2xx أو لم تستجب في غضون 5 ثوانٍ، فإن Truthlocks تعيد محاولة التسليم مع تراجع أسي:

| المحاولة | التأخير التقريبي |
| :- | :- |
| المحاولة الأولى | \~1 ثانية |
| المحاولة الثانية | \~2 ثانية |
| المحاولة الثالثة | \~4 ثوانٍ |
| المحاولة الرابعة | \~16 ثانية |
| المحاولة الخامسة | \~1 دقيقة |
| المحاولة السادسة | \~2 دقيقة |
| المحاولة السابعة | \~5 دقائق (حد أقصى) |

تشمل التأخيرات ما يصل إلى 30% من التذبذب. بعد 8 محاولات إجمالية (محاولة أولية واحدة + 7 محاولات إعادة)، يتم وضع علامة على التسليم على أنه فاشل.

يمكنك عرض محاولات التسليم وتفاصيل الفشل في **الإعدادات > Webhooks** بالنقر على نقطة نهاية، أو الاستعلام عنها عبر واجهة برمجة التطبيقات:

```http Request theme={null}
GET /v1/webhooks/endpoints/{id}/deliveries
X-API-Key: tl_live_...
```

راجع [مرجع API لتسليم القوائم](https://docs.truthlocks.com/ar/api-reference/webhooks/list-deliveries.md) للحصول على تفاصيل الاستجابة.

## تدوير الأسرار

إذا تم اختراق سر webhook الخاص بك، فقم بتدويره على الفور:

1. في لوحة تحكم المستأجر، انتقل إلى **الإعدادات > Webhooks** وانقر على نقطة النهاية.
2. انقر على **تدوير السر**.
3. انسخ السر الجديد — يتوقف السر القديم عن العمل فورًا.

يمكنك أيضًا التدوير عبر واجهة برمجة التطبيقات:

```http Request theme={null}
POST /v1/webhooks/endpoints/{id}/rotate
X-API-Key: tl_live_...
```

## اختبار خطافات الويب (webhooks)

أرسل حدث اختبار للتحقق من أن نقطة النهاية تعمل:

1. في لوحة تحكم المستأجر، انتقل إلى **الإعدادات > Webhooks** وانقر على نقطة النهاية.
2. انقر على **إرسال اختبار**.
3. يتم إرسال حدث `webhook.test` إلى عنوان URL الخاص بك باستخدام مسار التوقيع والتسليم الكامل.

عبر واجهة برمجة التطبيقات:

```http Request theme={null}
POST /v1/webhooks/test-delivery
X-API-Key: tl_live_...
Content-Type: application/json

{
  "endpoint_id": "ep_abc123",
  "event_type": "webhook.test",
  "payload": { "status": "ok", "source": "test-delivery" }
}
```

حقلا `event_type` و`payload` اختياريان - يتم تعيينهما افتراضيًا إلى `webhook.test` وحمولة حالة أساسية إذا تم حذفهما.

## إشعارات إشارة المخاطر

يمكنك تلقي إشعارات الويب هوك في الوقت الفعلي كلما تم إنشاء إشارة مخاطر بواسطة أي من مسارات الكشف الخمسة [جدار حماية هوية مكافحة الاحتيال](https://docs.truthlocks.com/ar/guides/risk-signals.md) — الاستيعاب المباشر، وتطبيع الأحداث، ومسح التزييف العميق، واكتشاف ATO، وتسجيل السرعة.

اشترك في `risk.signal.*` لتلقي جميع أحداث إشارة المخاطر، أو اشترك في `risk.signal.created` أو `risk.signal.escalated` بشكل فردي.

### حمولة مثال

```json theme={null}
{
  "id": "evt_r1s2k3...",
  "type": "risk.signal.created",
  "created_at": "2027-07-24T09:15:00Z",
  "data": {
    "signal_id": "a1b2c3d4-...",
    "signal_source": "velocity",
    "signal_type": "velocity",
    "risk_score": 72,
    "subject_type": "user",
    "subject_id": "usr_8f14e45f"
  }
}
```

### الاستجابة لإشارات المخاطر

استخدم خطافات الويب لإشارة المخاطر لتشغيل استجابات تلقائية — حظر جلسة مستخدم، أو إخطار فريق الأمان الخاص بك، أو التصعيد إلى حالة احتيال — دون استقصاء واجهة برمجة التطبيقات.

```javascript theme={null}
app.post("/webhooks/truthlock", (req, res) => {
  const event = JSON.parse(req.body.toString());

  if (event.type === "risk.signal.created") {
    const { risk_score, subject_id, signal_type } = event.data;

    if (risk_score >= 80) {
      // Critical — block immediately and alert security
      blockSubject(subject_id);
      notifySecurityTeam(event.data);
    } else if (risk_score >= 60) {
      // High — throttle and log for review
      throttleSubject(subject_id);
    }
  }

  res.status(200).json({ received: true });
});
```

> [!NOTE]
>
> تطلق webhooks إشارة المخاطر للإشارات التي تم إنشاؤها بواسطة جميع مسارات الكشف الخمسة. يخبرك حقل `signal_source` في الحمولة بالمسار الذي أنشأ الإشارة — `external`، `event_normalization`، `deepfake`، `ato`، أو `velocity`.

## أفضل الممارسات

> [!TIP]
>
> استجب لـ webhooks بسرعة. قم بمعالجة البيانات الثقيلة بشكل غير متزامن بعد إرجاع استجابة `200` لتجنب المهلات وإعادة المحاولات.

* **تحقق من كل توقيع.** لا تتخطى أبدًا التحقق من التوقيع، حتى في مرحلة التطوير.
* **استخدم قائمة انتظار الرسائل.** قم بوضع الأحداث الواردة في قائمة الانتظار ومعالجتها في عامل لتجنب حظر استجابة HTTP.
* **التعامل مع التكرارات.** استخدم رأس `X-Truthlocks-Event-Id` لإزالة تكرار الأحداث في حالة إعادة المحاولة.
* **مراقبة حالات فشل التسليم.** تحقق من علامة تبويب التسليمات في وحدة التحكم بانتظام بحثًا عن التسليمات الفاشلة أو المعطلة.
* **حافظ على سرية الأسرار.** قم بتخزين سر webhook الخاص بك في متغيرات البيئة، وليس في الكود المصدري.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.