أدوات Webhook

أداة Webhook هي نقطة نهاية HTTP واحدة خاصة بك، تصفها مرة واحدة وتسلّمها للوكيل. تعطيها اسماً، ووصفاً يقرؤه الوكيل، ورابطاً، وقائمة معاملات. عندما يقرر الوكيل استدعاءها، يصل الطلب إلى نقطة نهايتك وبيانات اعتمادك مضافة إليه بالفعل، ثم يقرأ الوكيل ردك ويواصل الحديث. تصف المنشئ الأداة في سطر واحد: "تتيح أداة الخادم للوكيل استدعاء واجهة برمجة خارجية أثناء المحادثة."

متى تستخدم هذا النوع

• نقطة نهاية واحدة بعدد قليل من المعاملات، وتريد كتابة الطلب بنفسك. هذه أداة Webhook.
• واجهة API كاملة فيها عمليات كثيرة. استورد المستند بدلاً من ذلك كـأداة OpenAPI، بدلاً من بناء أداة Webhook يدوياً لكل عملية.
• إجراء داخل منتج ربطته من قبل، مثل إضافة تفاعل في Slack أو إنشاء حدث في التقويم. استخدم أداة تكامل، فهي تأخذ عمليتها وبيانات اعتمادها من التكامل.

تُحفظ أدوات Webhook في مكتبة أدوات مساحة العمل، وتُمنح لوكيل بالاختيار، كما تُمنح كل أدوات مساحة العمل. انظر نظرة عامة على الأدوات للفرق بين المكتبة والاختيار لكل وكيل.

ما تحتاجه

• نقطة نهاية عامة يمكن الوصول إليها عبر HTTPS. تُرفض عناوين loopback والعناوين الخاصة وlink-local، لذلك لن تعمل خدمة على شبكتك الخاصة.
• عضوية مساحة العمل. إنشاء الأداة لا يحتاج إلى صلاحية إضافية.
• أي بيانات اعتماد تتطلبها نقطة النهاية، محفوظة أولاً كـسر أو كـاتصال مصادقة.

التعريف

افتح وكيلاً، وانتقل إلى تبويب الأدوات، واضغط إضافة أداة، ثم تبويب Webhook في النافذة. والنافذة نفسها موجودة في صفحة مكتبة الأدوات. تعديل أداة موجودة يفتح لوحة أعرض عنوانها تعديل الأداة، وتحتوي على عنصرين لا توجدان في نافذة الإنشاء: معاملات الجسم، وزر تبديل مطلوبة لكل معامل.

الاسم

مطلوب، ويجب أن يكون فريداً في مساحة العمل. يقترح النص داخل الحقل الشكل الذي يعمل معه الوكيل بأفضل صورة: مثال: lookup_order. تُحذف المسافات في بداية الاسم ونهايته. ويُرفض الاسم المستخدم من قبل بالرسالة A tool named "<name>" already exists in this workspace.

الوصف

هذا هو النص الذي يقرأه الوكيل ليقرر إن كان سيستدعي الأداة، ولهذا تعرض الخانة النص: "ماذا تفعل هذه الأداة؟ يستخدم الوكيل هذا ليقرّر متى يستدعيها." تحدّ نافذة إضافة أداة الوصف بـ 500 حرف وتعرض عدّاداً. اكتب الحالات التي تريد استخدام الأداة فيها، لا إعادة صياغة للاسم.

الطريقة

واحدة من GET أو POST أو PUT أو PATCH أو DELETE. تُحفظ بالحروف الكبيرة مهما كتبت.

الرابط

مطلوب، ويجب أن يكون رابط HTTPS عاماً. تظهر معاملات المسار كعناصر نائبة {curly}، كما يقول التلميح: "رابط https عام. ضع مَعلمات المسار بين أقواس معقوفة." ويُرفض الرابط الذي لا يجتاز الفحص بالرسالة url must be a public HTTPS URL (no loopback, private, or link-local addresses).

يجب أن تتطابق العناصر النائبة ومعاملات المسار تماماً في الاتجاهين. عنصر نائب بلا معامل خلفه يفشل بالرسالة URL placeholder {orderId} has no matching path parameter، ومعامل مسار لا يظهر في الرابط يفشل بالرسالة Path parameter "orderId" does not appear in the URL.

المهلة [مللي ثانية]

اختياري. يبدأ الحقل بالقيمة 10000. إذا تركته فارغاً فإن الاستدعاء ينتهي بعد 10000 ملّي ثانية. وأي قيمة فوق 30000 ملّي ثانية تُخفَّض إلى 30000 ملّي ثانية عند الاستدعاء.

المَعلمات

تُجمَّع المعاملات حسب المكان الذي تقع فيه في الطلب. تعرض نافذة إضافة أداة ثلاث مجموعات:

تضيف لوحة تعديل الأداة مجموعة رابعة هي معاملات الجسم، ووصفها هناك: "حقول ترسل في جسم الطلب JSON (POST/PUT/PATCH فقط)". إضافة معامل جسم تحت GET أو DELETE تُرفض بالرسالة GET requests cannot have body parameters.

لكل معامل الحقول التالية:

يُرفض معاملان بالاسم نفسه في المجموعة نفسها بالرسالة Duplicate query parameter "locale". ويُرفض الثابت بلا قيمة بالرسالة Constant parameter "locale" needs a value. ويُرفض السر خارج مجموعة الترويسات بالرسالة Secret parameter "X-Api-Key" is only allowed in headers، والسر بلا اختيار بالرسالة Secret parameter "X-Api-Key" needs a secretId.

القيمة الفارغة تُسقط ولا تُرسل: المعامل الذي تخرج قيمته undefined أو null أو نصاً فارغاً يُتخطى، فيبقى العنصر النائب في الرابط، ولا يظهر المفتاح أبداً في سلسلة الاستعلام أو في الجسم.

للحصول على أفضل نتيجة

نصان يحددان هل تعمل هذه الأداة: الوصف الذي يقرؤه الوكيل، والرد الذي ترسله نقطة نهايتك.

يجب أن يذكر الوصف متى يُستدعى الأداة وما الذي يعود منها، لأنه كل ما يحصل عليه الوكيل.

الموصى به

Look up a customer's order by its order number. Call this when the caller asks
where an order is, when it will arrive, or what it contained. Returns the status,
the carrier and the expected delivery date.

الأقل فاعلية

Order lookup. Calls the orders API.

يُقرأ ردك بصوت عالٍ في المحادثة، لذلك أرجِع الحقول القليلة التي يحتاجها الوكيل، وسمِّها بوضوح. إغراق الرد بسجل كامل يُبطئ الوكيل، وقد يدفع الاستجابة فوق الحد الأقصى البالغ 256 كيلوبايت.

الموصى به

{ "status": "shipped", "carrier": "Aramex", "expectedDelivery": "2026-09-18" }

الأقل فاعلية

{ "ok": true, "data": { "order": { "id": 4512, "lines": [], "customer": {}, "audit": [] } } }

المصادقة

المصادقة خطوة منفصلة عن المعاملات، ولها مساران.

اتصال المصادقة. اختر اتصالاً محفوظاً واحداً في مساحة العمل من حقل اتصال المصادقة، أو اتركه على بدون مصادقة. توجد أربعة أنواع: basic وbearer وOAuth2 client credentials وOAuth2 JWT. تصل الأنواع الأربعة كلها كـ Authorization header، فترى نقطة النهاية Basic … أو Bearer …. ترجيح header الاتصال على أي معامل header يحمل الاسم نفسه، لأن المصادقة تُكتب في الأخير. اتصال لم يعد موجوداً في مساحة العمل يُرفض عند الحفظ بالرسالة Referenced credential not found.

معامل header من نوع سر. أضف معامل header، واجعل القيمة سر، واختر سرّاً من مساحة العمل. تُقرأ القيمة وقت الاستدعاء، ولا تُحفظ على الأداة ولا تُعرض للوكيل أبداً. السر الذي لم يعد موجوداً يُرفض عند الحفظ بالرسالة Referenced secret not found. إذا تعذّرت قراءة السر وقت الاستدعاء، يُحذف الـ header ويُرسل الطلب على أي حال.

عندما يكون اتصال OAuth2 فاعلاً وترد نقطة نهايتك بالرمز 401، تجلب إيكونوڤا رمزاً جديداً وترسل الطلب مرة أخرى. هذه المحاولة تحدث للرمز 401 فقط، ومرة واحدة فقط.

الطلب الذي تستقبله نقطة النهاية

لنفترض أداة بالطريقة POST والرابط https://api.example.com/orders/{orderId}، ومعامل مسار orderId يملؤه الوكيل، ومعامل استعلام ثابت locale، وheader من نوع سر هو X-Api-Key، ومعامل جسم reason يملؤه الوكيل. يصل الطلب هكذا:

POST /orders/4512?locale=en HTTP/1.1
Host: api.example.com
X-Api-Key: <value of the workspace secret>
Content-Type: application/json

{"reason":"caller asked for a refund"}

ثلاثة أشياء تستحق الانتباه في هذا الطلب. يُضبط Content-Type: application/json فقط عندما تسمح الطريقة بجسم وخرجت قيمة معامل جسم واحدة على الأقل، ولا يستبدل أبداً header Content-Type الذي عرّفته بنفسك. قيم المسار تُرمّز بصيغة URL. لا تُتبع إعادة التوجيه، فإن رد 301 أو 302 يعود بتلك الحالة لا بالصفحة التي خلفها.

أعد تشغيل الطلب نفسه من جهازك للتأكد من نقطة النهاية وبيانات الاعتماد وشكل الاستجابة، قبل أن تمنح الأداة لوكيل.

curl -X POST "https://api.example.com/orders/4512?locale=en" \
  -H "X-Api-Key: $MY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"caller asked for a refund"}'

import os
import requests

response = requests.post(
    "https://api.example.com/orders/4512",
    params={"locale": "en"},
    headers={"X-Api-Key": os.environ["MY_API_KEY"]},
    json={"reason": "caller asked for a refund"},
    timeout=10,
)
print(response.status_code, response.text[:500])

const response = await fetch('https://api.example.com/orders/4512?locale=en', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.MY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ reason: 'caller asked for a refund' }),
});
console.log(response.status, (await response.text()).slice(0, 500));

ما الذي يراه الوكيل

يستلم الوكيل اسم الأداة ووصفها، ومخطط JSON مبنياً على المعاملات التي قيمتها مُنشأ بالذكاء الاصطناعي. تُحذف الثوابت والأسرار من هذا المخطط تماماً، فلا يراها الوكيل، ولا يستطيع تغييرها، ولا يمكن إقناعه بكشفها. الأداة التي لا تحمل معاملاً مُنشأ بالذكاء الاصطناعي تصل إلى الوكيل دون أي معامل، ويذكر المنشئ ذلك بوضوح: "لا توجد مَعلمات. سيستدعي الوكيل نقطة النهاية كما هي."

يحمل كل خاصية في المخطط نوع بيانات المعامل، وإذا كتبت واحداً، فـ الوصف الخاص به، وهو الجملة التي يستخدمها الوكيل ليعرف ما يضعه هناك. المعاملات المعلّمة كمطلوبة تُدرج كمطلوبة.

أداة Webhook المختارة أمام الوكيل في كل دور. لا يُبحث فيها ولا تُرتّب، لذلك عندما لا تُستدعى أداة Webhook أبداً، فالوصف هو المكان الذي تنظر فيه.

يعود ردك إلى الوكيل كحالة وعلامة ok وجسم. يُقرأ الجسم كـ JSON إذا حملت استجابتك application/json، ويُمرَّر كنص في غير ذلك.

تحقق منها قبل أن يفعلها المتصل

ليس لأداة Webhook زر تشغيل في البوابة، ولا تظهر في اختبار الاسترجاع، الذي يبحث في عمليات OpenAPI المستوردة وأسئلة قواعد البيانات فقط. تحقق منها في خطوتين:

1. أعد تشغيل الطلب بنفسك باستخدام التبويبات أعلاه، للتأكد من نقطة النهاية وبيانات الاعتماد وشكل الاستجابة.
2. تحدّث مع الوكيل في ساحة التجربة، وقل الشيء الذي يجب أن يُطلق الاستدعاء. انظر اختبر وكيلك.

الحدود

استكشاف الأخطاء وإصلاحها

الوكيل لا يستدعي الأداة أبداً

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

يفشل الاستدعاء برسالة "Tool request failed or timed out"

لم ترد نقطة نهايتك خلال المهلة، أو فشل الاتصال. ارفع المهلة [مللي ثانية] حتى الحد الأقصى 30000 ملّي ثانية، وتأكد من أن المضيف يُحَلّ إلى عنوان عام عبر HTTPS.

يفشل الاستدعاء برسالة "Tool response too large"

أعلنت نقطة نهايتك عن استجابة أكبر من 256 كيلوبايت. أرجِع حمولة أصغر: على الوكيل أن يقرأ النتيجة داخل المحادثة، لذلك يتفوق الكائن المختصر على السجل الكامل.

نقطة نهايتك لا ترى أي بيانات اعتماد

إما أنه لم يُختَر اتصال مصادقة، أو تعذّرت قراءة السر خلف معامل header. السر غير المقروء يُحذف ويُرسل الطلب على أي حال، فالعَرَض هو header مفقود وليس استدعاءً فاشلاً. أعد اختيار السر على المعامل ثم احفظ.

ما زال العنصر النائب للمسار في الرابط

جاءت قيمة ذلك المعامل فارغة، والقيمة الفارغة تُتخطى، فيبقى {placeholder} كما هو. علّم المعامل كمطلوب ليضطر الوكيل إلى ملئه.

الأسئلة الشائعة

هل يستطيع الوكيل اختيار الرابط؟

لا. الرابط والطريقة وموضع كل معامل ثابتة على الأداة. الوكيل يملأ فقط قيم المعاملات المضبوطة على مُنشأ بالذكاء الاصطناعي.

من أين ترى نقطة نهايتي أن الاستدعاء يأتي؟

طلب HTTPS عادي من إيكونوڤا، لا يحمل إلا المعاملات وبيانات الاعتماد التي ضبطتها. لا شيء فيه يُعرّف المتصل أو المحادثة، ولا شيء يوقّعه، لذلك فإن فحص بيانات الاعتماد الذي تنفذه أنت هو كل التحكم في الوصول.

هل هذا هو نفسه Webhook المطورين؟

لا، والأسماء هي الشيء المربك الوحيد هنا. أداة Webhook استدعاء صادر يجريه الوكيل إلى واجهتك أثناء المحادثة. أما Webhook المطورين فتسليم وارد تُرسله إيكونوڤا إليك عندما يقع حدث في المنصة. انظر إعداد Webhook لذلك النوع.

ماذا يحدث عند حذف الأداة؟

تُزال من المكتبة، وتُلغى تحديدها من كل وكيل كان يستخدمها. تعرض البوابة ذلك قبل أن تؤكد: "سيؤدي هذا إلى حذف الأداة والبيانات السرية المرتبطة بها، وإلغاء تحديدها من جميع الوكلاء الذين يستخدمونها. ولا يمكن التراجع عن هذا الإجراء." اتصالات المصادقة قابلة لإعادة الاستخدام، ولا تُحذف مع الأداة.

هل أستطيع توجيه أداة إلى خدمة داخل شبكتي؟

لا. يجب أن يكون المضيف عاماً. تُحجب كل نطاقات loopback والنطاقات الخاصة وعناوين link-local ونطاقات NAT على مستوى مزوّد الخدمة، في IPv4 وIPv6، وقت الحفظ ومرة أخرى وقت الاستدعاء.

هل تؤثر إزالة الأداة من وكيل واحد في الباقين؟

لا. الإزالة تغيّر اختيار ذلك الوكيل وحده. سجل المكتبة وكل وكيل آخر يبقيان كما هما.

صفحات ذات صلة

• أدوات OpenAPI: استورد واجهة API كاملة بدلاً من نقطة نهاية واحدة في كل مرة
• أسرار مساحة العمل: خزّن مفتاح API الذي ترسله هذه الأداة
• اتصالات المصادقة: بيانات اعتماد basic وbearer وOAuth2
• اختبر وكيلك: أطلق الاستدعاء في ساحة التجربة
• نظرة عامة على الأدوات: كيف تختلف الأنواع الأربعة
• إعداد Webhook: النوع الوارد، وهو ميزة مختلفة