الـ Webhooks

تتيح لك الـ Webhooks أن يرسل Gurdx رسالة JSON موقّعة إلى خادمك لحظة اكتشاف حدث خطِر، فتتصرف فورًا دون الحاجة إلى الاستعلام الدوري.

كيف تعمل#

عندما ينتج طلب API نتيجة خطِرة (مثل عنوان IP مشبوه أو عملية دفع عالية الخطورة)، يحفظ Gurdx حدثًا ثم يضع في قائمة الانتظار عملية تسليم واحدة لكل Webhook مفعّل ومشترك في هذا النوع من الأحداث. كل تسليم هو طلب POST عبر HTTPS بجسم JSON وترويسة توقيع. طلبات الوضع التجريبي (mode=test أو مفتاح gx_test_) لا تُنشئ أحداثًا، لذلك لا تُشغّل أي Webhook.

أنشئ الـ Webhooks من لوحة التحكم https://gurdx.cretip.com/app ضمن الإعدادات. لكل Webhook عنوان URL وقائمة بأنواع الأحداث المشترك بها (أو * للجميع) وسرّ يُستخدم في التوقيع.

أسماء الأحداث#

تستخدم الـ Webhooks أسماء أحداث عامة ثابتة. اسم واحد يختلف عن النوع الداخلي: النوع suspicious_ip يُسلَّم باسم proxy_detected.

Note: عند اختيار الأحداث التي يشترك بها الـ Webhook تختار من الأنواع الداخلية الظاهرة في لوحة التحكم (فاكتشاف VPN والبروكسي هو suspicious_ip هناك). أما مستقبِلك فيرى دائمًا الاسم المُسلَّم من العمود الأول، في الجسم وفي ترويسة X-Gurdx-Event.

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

حمولة الرسالة#

يبدأ الجسم باسم الحدث، ثم تفاصيله، ثم درجة الخطورة، ثم معرّف المستخدم الذي أرسلته عبر userID (أو null)، ثم الوقت بصيغة ISO-8601.

{
  "event": "proxy_detected",
  "ip": "203.0.113.42",
  "countryCode": "NL",
  "security": { "isProxy": true, "proxyType": "VPN", "isTor": false },
  "risk_score": 78.5,
  "user_identifier": "user_1042",
  "occurred_at": "2026-10-06T09:14:22+00:00"
}

تختلف حقول التفاصيل بين event وrisk_score حسب نقطة النهاية التي أنتجت الحدث. اعتمد في برمجتك على event وrisk_score وuser_identifier وoccurred_at، وعامل الباقي كحقول اختيارية.

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

يُحسب التوقيع على البايتات الدقيقة لجسم الطلب باستخدام سرّ الـ Webhook الذي ظهر عند إنشائه. تحقق دائمًا قبل تحليل JSON، وقارن بطريقة ثابتة الزمن.

<?php
$secret = getenv('GURDX_WEBHOOK_SECRET');
$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_GURDX_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);

if (! hash_equals($expected, $header)) {
    http_response_code(401);
    exit('invalid signature');
}

$event = json_decode($raw, true);
// ...handle $event['event']
http_response_code(204);

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// Keep the raw body: re-serialising parsed JSON changes the bytes.
app.post('/gurdx', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.GURDX_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');
  const received = req.get('X-Gurdx-Signature') || '';

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body.toString('utf8'));
  // ...handle event.event
  res.sendStatus(204);
});

التسليم وإعادة المحاولة#

• ينتظر Gurdx الرد حتى 10 ثوانٍ، وأي حالة 2xx تُعدّ نجاحًا.
• أي شيء آخر (حالة غير 2xx، أو انتهاء المهلة، أو فشل الاتصال) يُعاد. تُجرى المحاولة 5 مرات كحدّ أقصى، بفواصل 10 ثوانٍ ثم دقيقة ثم 5 دقائق ثم 30 دقيقة.
• تُسجَّل كل محاولة مع رمز الحالة ومقتطف من الرد والمدة.
• بعد 20 فشلًا متتاليًا على الـ Webhook يعطّله Gurdx تلقائيًا، ويعيد أي تسليم ناجح العدّاد إلى الصفر. أعد تفعيله من لوحة التحكم بعد إصلاح نقطة الاستقبال.

عدم تكرار المعالجة (Idempotency)#

قد يصلك الحدث نفسه أكثر من مرة بسبب إعادة المحاولة أو تكرار نادر في الطابور. استخدم ترويسة X-Gurdx-Delivery (رقم الحدث) كمفتاح فريد: احفظه وتجاهل أي تسليم عالجته سابقًا.

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

1. تحقق من التوقيع قبل تحليل الجسم أو الوثوق بأي شيء فيه.
2. أجب بـ 2xx بسرعة ثم نفّذ العمل الثقيل في مهمة خلفية.
3. اعتبر risk_score إشارة وليس حكمًا نهائيًا، ودمجه مع سياقك الخاص.
4. احفظ السرّ في متغير بيئة وبدّله إذا تسرّب.
5. استخدم HTTPS لنقطة الاستقبال، وسجّل رقم X-Gurdx-Delivery مع كل حدث تعالجه.

انظر أيضًا الأحداث والتنبيهات ونظرة عامة على التكاملات.