مرجع حمولة Webhook
حين تجتاز إرسالية التحقّق، يرسل المُحوِّل POST واحدًا إلى رابط webhook المُعَدّ. هذه الصفحة هي العقد الدقيق لذلك الطلب. لشرح الإعداد، انظر أعدّ التحقّق المُستضاف؛ وللمفهوم، انظر تحقّق دون خادم خلفي.
سطر الطلب والترويسات
يرسل المُحوِّل POST بجسم JSON وهذه الترويسات:
| الترويسة | القيمة |
|---|---|
content-type | application/json |
accept | application/json |
user-agent | Caputchin-Forwarder/0.1 |
x-caputchin-test | 1، موجودة فقط على اختبار التسليم من لوحة التحكّم؛ غائبة على الإرساليات الحقيقية |
يُرسَل النداء مع تعطيل عمليات إعادة التوجيه ومهلة بضع ثوانٍ. الطلب غير موقّع؛ سرّية رابط webhook هي ما يصادقه.
الجسم
الجسم كائن JSON بمفتاحين على المستوى الأعلى، caputchin (بيانات تحقّق وصفية يضيفها Caputchin) وform (حقولك المُرسَلة):
{
"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، أو مهلة، أو فشل اتّصال كتسليم فاشل، والتسليم الفاشل لا يُعاد. تتبّع صحّة التسليم على صفحة الإحصاءات.
انظر أيضًا
- أعدّ التحقّق المُستضاف: اربط webhook وأطلِق تسليمًا اختباريًّا.
- تحقّق دون خادم خلفي: المفهوم، وموقف الخصوصية، وقواعد أمان الرابط.
- إحصاءات التحقّق المُستضاف: قراءة نجاح التسليم وفشله.