Webhooks — بوابة الأحداث الشاملة

تخيل هذا: مطوّر يفتح طلب سحب (Pull Request) على GitHub، وفي غضون ثوانٍ، يكون وكيل الذكاء الاصطناعي الخاص بك قد راجع الكود بالفعل وعلّق عليه. أو فشلت عملية دفع على Stripe، فيقوم وكيلك تلقائيًا بإشعار فريقك على Telegram. هذا هو سحر الـ Webhooks — فهي تتيح للخدمات الخارجية أن تطرق باب وكيلك وتقول: “مرحبًا، حدث شيء للتو، يرجى التعامل معه.”

ما هي الـ Webhooks؟

الـ Webhooks تشبه جرس الباب لتطبيقاتك. بدلًا من التحقق المستمر من حدوث تغييرات (Polling)، تنتظر ببساطة حتى يرن الجرس. عندما يرسل GitHub أو GitLab أو JIRA أو Stripe أو أي خدمة أخرى طلب HTTP POST إلى نقطة نهاية الـ Webhook الخاصة بك، يستيقظ وكيل Hermes الخاص بك، ويعالج الحدث، ويتخذ الإجراء المناسب.

أفضل ما في الأمر؟ يمكن لوكيلك الاستجابة بطرق متعددة — التعليق على طلبات السحب، إرسال رسائل إلى Telegram أو Discord، أو ببساطة تسجيل النتيجة لمراجعتها لاحقًا.

بدء سريع

البدء أسهل مما تتخيل:

فعّل محوّل الـ Webhook عبر hermes gateway setup أو متغيرات البيئة
عرّف المسارات في config.yaml أو أنشئها ديناميكيًا باستخدام hermes webhook subscribe
وجّه خدمتك إلى http://your-server:8644/webhooks/<route-name>

هذا كل شيء. وكيلك الآن في الخدمة.

إعداد البوابة (Gateway)

لديك طريقتان لتفعيل الـ Webhooks، اختر ما يناسبك.

الخيار 1: معالج الإعداد

hermes gateway setup

اتبع التعليمات لتفعيل الـ Webhooks، واختر المنفذ (Port)، وعيّن مفتاح HMAC عام. سيتولى المعالج كل التكوين الممل نيابةً عنك.

الخيار 2: متغيرات البيئة

أضف هذه الأسطر إلى ملف ~/.hermes/.env:

WEBHOOK_ENABLED=true
WEBHOOK_PORT=8644        # الافتراضي
WEBHOOK_SECRET=your-global-secret

بمجرد تشغيل البوابة، تحقق من أنها تعمل:

curl http://localhost:8644/health

يجب أن ترى:

{"status": "ok", "platform": "webhook"}

تكوين المسارات (Routes)

المسارات هي قلب معالجة الـ Webhooks. كل مسار يخبر وكيلك كيف يتعامل مع الأحداث من مصدر معين. اعتبرها تعليمات مخصصة لأنواع مختلفة من الزوار.

إليك ما يمكنك تكوينه لكل مسار:

الخاصية	وظيفتها
`events`	أنواع الأحداث التي سيتم قبولها (مثل `["pull_request"]`). اتركها فارغة لقبول كل شيء.
`secret`	مفتاح HMAC للتحقق من التوقيع. استخدم `"INSECURE_NO_AUTH"` للاختبار فقط.
`profile`	الملف الشخصي الذي يمكنه تنفيذ هذا المسار (مفيد مع تعدد الإرسال).
`prompt`	قالب نصي باستخدام تدوين النقاط مثل `{pull_request.title}`. احذفه لإخراج كامل حمولة JSON.
`filters`	شروط تعريفية لتجاهل الحمولات غير المرغوب فيها قبل تشغيل الوكيل.
`script`	سكربت تصفية/تحويل يمكنه تعديل الحمولة قبل تطبيق القالب.
`skills`	المهارات التي سيتم تحميلها لهذه الجلسة من الوكيل.
`toolsets`	الأدوات التي يمكن للوكيل استخدامها (يستبدل مجموعة أدوات الـ Webhook الافتراضية).
`deliver`	أين يتم إرسال الاستجابة: `github_comment`، `telegram`، `discord`، `slack`، `log`، والمزيد.
`deliver_extra`	تفاصيل إضافية للتسليم مثل اسم المستودع أو معرف الدردشة.
`deliver_only`	تخطَّ الوكيل تمامًا وسلّم القالب المعروض كما هو. تكلفة LLM صفرية!

مثال من الواقع

لنلقِ نظرة على إعداد عملي. إليك مسار يراجع طلبات السحب:

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      secret: "global-fallback-secret"
      routes:
        github-pr:
          events: ["pull_request"]
          secret: "github-webhook-secret"
          prompt: |
            Review this pull request:
            Repository: {repository.full_name}
            PR #{number}: {pull_request.title}
            Author: {pull_request.user.login}
            URL: {pull_request.html_url}
            Diff URL: {pull_request.diff_url}
            Action: {action}
          skills: ["github-code-review"]
          deliver: "github_comment"
          deliver_extra:
            repo: "{repository.full_name}"
            pr_number: "{number}"

وإليك مسار يرسل إشعار Telegram فقط عندما يدفع شخص ما إلى الفرع الرئيسي:

        deploy-notify:
          events: ["push"]
          secret: "deploy-secret"
          prompt: "New push to {repository.full_name} branch {ref}: {head_commit.message}"
          filters:
            - field: "ref"
              equals: "refs/heads/main"
          deliver: "telegram"

التصفية الذكية

ميزة filters مفيدة بشكل خاص. غالبًا ما ترسل المزودات سيلًا من الأحداث، لكنك تهتم ببعضها فقط. تتيح لك الفلاتر تجاهل الضوضاء قبل أن يستيقظ وكيلك. الحمولات غير المتطابقة تحصل على رد مهذب {"status":"ignored","reason":"filter"} مع HTTP 200 — لا إهدار للحوسبة، ولا استدعاءات LLM غير ضرورية.

وضع التسليم المباشر

إليك خدعة ذكية: عيّن deliver_only: true ولن يعمل وكيلك إطلاقًا. يصبح قالب الـ prompt المعروض هو الرسالة الحرفية التي يتم تسليمها. هذا يعني تسليمًا في أقل من ثانية بتكلفة LLM صفرية. مثالي للإشعارات البسيطة التي لا تحتاج إلى تفكير ذكي.

ملاحظة أمنية

تذكر: المصادقة لا تعني الثقة. حقول الحمولة من الـ Webhooks هي بيانات غير موثوقة. تحقق دائمًا وعقّم أي شيء تستخدمه في القوالب أو الـ prompts. يجب أن يتعامل وكيلك مع محتوى الـ Webhook كما يتعامل مع إدخال المستخدم — بشك صحي.

الخلاصة

تحوّل الـ Webhooks وكيل Hermes الخاص بك إلى مساعد سريع الاستجابة يتفاعل مع العالم في الوقت الفعلي. سواء كنت تؤتمت مراجعات الكود، أو ترسل إشعارات النشر، أو تبني سير عمل معقدًا قائمًا على الأحداث، فإن محوّل الـ Webhook يجعل كل ذلك ممكنًا ببضعة أسطر من YAML.