---
type: reference
title: مرجع حمولة Webhook
summary: الطلب الدقيق الذي يستقبله webhook التحقّق المُستضاف، كل حقل في الجسم، والترويسات التي يرسلها Caputchin.
---

حين تجتاز إرسالية التحقّق، يرسل المُحوِّل `POST` واحدًا إلى رابط webhook المُعَدّ. هذه الصفحة هي العقد الدقيق لذلك الطلب. لشرح الإعداد، انظر [أعدّ التحقّق المُستضاف](/docs/hosted-verification/set-up)؛ وللمفهوم، انظر [تحقّق دون خادم خلفي](/docs/hosted-verification/overview).

## سطر الطلب والترويسات

يرسل المُحوِّل `POST` بجسم JSON وهذه الترويسات:

| الترويسة | القيمة |
|---|---|
| `content-type` | `application/json` |
| `accept` | `application/json` |
| `user-agent` | `Caputchin-Forwarder/0.1` |
| `x-caputchin-test` | `1`، موجودة فقط على **اختبار التسليم** من لوحة التحكّم؛ غائبة على الإرساليات الحقيقية |

يُرسَل النداء مع تعطيل عمليات إعادة التوجيه ومهلة بضع ثوانٍ. الطلب غير موقّع؛ سرّية رابط webhook هي ما يصادقه.

## الجسم

الجسم كائن JSON بمفتاحين على المستوى الأعلى، `caputchin` (بيانات تحقّق وصفية يضيفها Caputchin) و`form` (حقولك المُرسَلة):

```json
{
  "caputchin": {
    "site_key": "cpt_pub_...",
    "session_id": "...",
    "game_id": "caputchin/games/leaf-memory",
    "score": 847,
    "duration_ms": 4200,
    "verified_at": 1748640000000
  },
  "form": {
    "email": "visitor@example.com",
    "message": "Hello!"
  }
}
```

### كائن `caputchin`

| الحقل | النوع | المعنى |
|---|---|---|
| `site_key` | string | المفتاح العام `cpt_pub_...` الذي جاءت منه الإرسالية. |
| `session_id` | string | معرّف جلسة تحقّق معتم، مفيد للربط أو إزالة التكرار. على تسليم اختباري يسبقه `test_`. |
| `game_id` | string or null | اللعبة التي لعبها الزائر. null حين جرى التحقّق بلا لعبة. |
| `score` | number or null | نتيجة اللعبة. بيانات وصفية يدّعيها العميل للتحليلات، لا إشارة ثقة أبدًا. null حين لا تنطبق. |
| `duration_ms` | number or null | كم قضى الزائر يلعب اللعبة، بالميلّي ثانية. يدّعيها العميل، لا إشارة ثقة. null حين لا تنطبق (مثلًا تحقّق بلا لعبة). |
| `verified_at` | number | متى تحقّق Caputchin من الرمز، كـ Unix epoch بالميلّي ثانية. |
| `test` | boolean (optional) | موجود و`true` فقط على تسليم اختباري من لوحة التحكّم. غائب على الإرساليات الحقيقية. |

‏`game_id`، و`score`، و`duration_ms` كلٌّ قابل لأن يكون null على إرسالية حقيقية، فاحرس ضدّ null قبل قراءتها. لا أحد من حقول `caputchin` قرار ثقة: الثقة هي أن الطلب وصل أصلًا، لأن إرسالية تفشل في التحقّق لا تُحوَّل أبدًا.

### كائن `form`

‏`form` كائن مسطّح من حقولك المُرسَلة كمفاتيح نصّية وقيم نصّية، تمامًا كما أُرسِلت، بتغيير واحد: حقل `caputchin-token` يُزال قبل التسليم، فلا يظهر هنا أبدًا. يقبل المُحوِّل حقولًا نصّية فقط؛ وإرسالية تحمل رفع ملفّ تُرفَض قبل أي تسليم.

## ما الذي ينبغي أن يعيده معالِجك

أعِد أي حالة `2xx` للإقرار بالاستلام. يعامل المُحوِّل استجابة غير `2xx`، أو مهلة، أو فشل اتّصال كتسليم فاشل، والتسليم الفاشل لا يُعاد. تتبّع صحّة التسليم على صفحة [الإحصاءات](/docs/hosted-verification/statistics).

## انظر أيضًا

- [أعدّ التحقّق المُستضاف](/docs/hosted-verification/set-up): اربط webhook وأطلِق تسليمًا اختباريًّا.
- [تحقّق دون خادم خلفي](/docs/hosted-verification/overview): المفهوم، وموقف الخصوصية، وقواعد أمان الرابط.
- [إحصاءات التحقّق المُستضاف](/docs/hosted-verification/statistics): قراءة نجاح التسليم وفشله.