المطورون / Tools
إنشاء أداة webhook
https://api.echonova.ai/v1/tools/webhookتنشئ أداة تستدعي عنوان URL عامًا واحدًا بصيغة https مع المعاملات التي تحددها. تُشار قيم الترويسات السرية وروابط المصادقة بمعرّفاتها، ويُرفض أي نص عادي يبدو كبيانات اعتماد. يأخذ الطلب الاستدعاء تحت `webhook.target.url`، ويعرضه الرد باسم `webhook.url`. أرسل `Idempotency-Key` لإعادة المحاولة بأمان. الحد: 20 طلبًا في الدقيقة لكل مفتاح. تُشار الأسرار بمعرّفها من `GET /v1/secrets`، ولا تُدخل قيمها إلا في خزنة البوابة. استخدام هذه النقطة مجاني. يحتاج المفتاح إلى النطاق `tools:write`.
Headers
كلمة Bearer ثم مسافة ثم مفتاح API الذي يبدأ بـ ek_. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.
اختياري. كرّر المفتاح نفسه خلال 24 ساعة لإعادة المحاولة بأمان: تعود النتيجة الأولى، ولا يُنشأ شيء مرتين. الطلب الجديد يحتاج إلى مفتاح جديد.
متن الطلب
application/json
اسم الأداة، ويجب أن يكون فريدًا في مساحة العمل.
وظيفة الأداة.
الاستدعاء الذي تنفذه الأداة.
الاستجابة
200 application/json كل استجابة تستخدم هذا الغلاف.
النتيجة.
معرّف الأداة.
اسم الأداة، ويكون فريدًا في مساحة العمل.
webhook أو openapi أو integration.
وظيفة الأداة، أو `null`.
وقت إنشاء الأداة.
وقت آخر تغيير على الأداة.
يُعبأ لأدوات webhook. لا تُعاد القيم الثابتة أبدًا.
عنوان URL الذي تستدعيه الأداة.
طريقة HTTP للاستدعاء.
أقصى مدة للاستدعاء بالمللي ثانية، أو `null` للقيمة الافتراضية.
معرّف ربط المصادقة المستخدم في الاستدعاء، أو `null`.
القيم التي يرسلها الاستدعاء.
مكان المعامل في الطلب.
مفتاح المعامل، أو اسم العنصر النائب في المسار.
نوع القيمة التي يأخذها المعامل.
هل يحتاج الاستدعاء إلى هذا المعامل.
يوضح للنموذج ما يضعه هنا، أو `null`.
llm أو constant أو secret. لا تُعاد القيم الثابتة أبدًا.
معرّف السر في الخزنة عندما يكون valueType هو secret، وإلا فهو `null`.
يُعبأ لأدوات OpenAPI.
عنوان مستند OpenAPI المستورد.
عدد العمليات التي استوردتها الأداة.
هل صار الاستيراد جاهزًا للوكلاء.
الخادم الذي تستدعيه الأداة، أو `null`.
أسماء العمليات المختارة للاستيراد، والقائمة الفارغة تعني الكل.
معرّف ربط المصادقة المرسل مع كل استدعاء، أو `null`.
سبب فشل الاستيراد، أو `null`.
يُعبأ لأدوات التكامل.
مزوّد التكامل.
مفتاح أداة التكامل.
قيمته true عند نجاح الطلب.
يكرر رمز حالة HTTP.
قيمته null عند النجاح.
الأخطاء
الغلاف نفسه، مع success بقيمة false و data بقيمة null. كل الأخطاء
متى يحدث. معامل أو عنصر في `fieldValues` له valueType هو constant، واسمه يبدو كبيانات اعتماد مثل Authorization أو token أو api key أو cookie. الرسالة تذكر الحقل ولا تذكر قيمته أبدًا.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم ربط مصادقة.
متى يحدث. قيمة ثابتة تبدأ بـ `Bearer` أو `Basic` أو `Token` أو `Digest`، أو لها شكل JWT. الرسالة تذكر الحقل ولا تذكر قيمته أبدًا.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم ربط مصادقة.
متى يحدث. عنوان url الخاص بـ webhook أو `baseUrlOverride` فيه مفتاح استعلام يبدو كبيانات اعتماد. الرسالة تذكر المفتاح ولا تذكر قيمته أبدًا.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم ربط مصادقة.
متى يحدث. مفتاح يبدو كبيانات اعتماد مخفي في جزء الاستعلام أو جزء الـ fragment من عنوان url الخاص بـ webhook أو `baseUrlOverride`.
الحل. احفظ القيمة في خزنة البوابة، ثم أرسلها كترويسة سرية مع `secretId` الخاص بها، أو استخدم ربط مصادقة.
متى يحدث. عنوان webhook لا يستخدم https، أو يشير إلى عنوان loopback أو خاص أو link-local، أو ليس عنوان URL.
الحل. أرسل عنوان https عامًا.
متى يحدث. عنوان webhook يحمل اسم مستخدم أو كلمة مرور.
الحل. أرسل العنوان بدونهما، واستخدم header سريًّا أو اتصال مصادقة.
متى يحدث. قيمة `secretId` أو `connectionId` أو `authConnectionId` ليست معرّفًا صالحًا من 24 حرفًا سداسيًا عشريًا. الرسالة تذكر الحقل.
الحل. استخدم معرّفًا من `GET /v1/secrets` أو `GET /v1/auth-connections`.
متى يحدث. `secretId` غير معروف، أو يتبع مساحة عمل أخرى.
الحل. استخدم معرّفًا من `GET /v1/secrets`.
متى يحدث. `connectionId` أو `authConnectionId` غير معروف، أو يتبع مساحة عمل أخرى، أو هو ربط تديره قناة.
الحل. استخدم معرّفًا من `GET /v1/auth-connections`.
متى يحدث. معامل له valueType هو secret ولا يحمل `secretId`. الرسالة تذكر المعامل.
الحل. أرسل `secretId` من `GET /v1/secrets`.
متى يحدث. معامل له valueType هو secret وليس في موقع header. الرسالة تذكر المعامل.
الحل. أرسل السر كمعامل في الترويسة (header).
متى يحدث. عنوان url الخاص بـ webhook فيه عنصر نائب مثل `{placeholder}` ولا يوجد معامل مسار بهذا الاسم.
الحل. أضف معامل مسار لكل عنصر نائب.
متى يحدث. معامل مسار لا يظهر له `{name}` في عنوان url الخاص بـ webhook.
الحل. ضع `{name}` في عنوان url، أو احذف المعامل.
متى يحدث. webhook من نوع GET أو DELETE فيه معامل في الجسم. الرسالة تذكر الطريقة.
الحل. استخدم معامل استعلام، أو غيّر الطريقة إلى POST أو PUT أو PATCH.
متى يحدث. اسم معامل فارغ.
الحل. أعطِ كل معامل اسمًا.
متى يحدث. معاملان لهما الموقع نفسه والاسم نفسه. الرسالة تذكرهما.
الحل. اذكر كل معامل مرة واحدة.
متى يحدث. معامل له valueType هو constant ولا يحمل `constantValue`.
الحل. أرسل `constantValue`.
متى يحدث. ترويسة `Idempotency-Key` أطول من 200 حرف، أو تحتوي على مسافة أو على حرف خارج ASCII القابل للطباعة.
الحل. أرسل من 1 إلى 200 حرف ASCII قابل للطباعة، مثل UUID.
متى يحدث. متن الطلب أو الاستعلام يحمل حقلًا لا تعرّفه نقطة النهاية.
الحل. احذف الحقل.
متى يحدث. header `Authorization` مفقود، أو قيمته لا تبدأ بـ `Bearer ek_...`، أو أن الرمز لا يطابق أي مفتاح، أو أن المفتاح محذوف أو معطّل أو منتهي الصلاحية، أو أن حسابه مغلق.
الحل. أرسل `Authorization: Bearer ek_...` بمفتاح API مفعّل من هذه البيئة.
متى يحدث. مساحة العمل التي يتبعها المفتاح ليس لديها اشتراك.
الحل. تحقّق من خطة مساحة العمل في البوابة.
متى يحدث. حالة الاشتراك ليست نشطة ولا تجريبية.
الحل. جدّد الاشتراك.
متى يحدث. المفتاح لا يملك النطاق `tools:write`. النطاق `agents:write` لا يمنحه هذه الصلاحية.
الحل. عدّل المفتاح وأعطه النطاق `tools:write`، أو استخدم مفتاحًا آخر.
متى يحدث. العضو الذي أنشأ المفتاح غادر مساحة العمل، أو لم يعد لديه الصلاحيتان `Manage tools` و`Manage developer API` معًا. يُفحص هذا مع كل طلب.
الحل. أعطِ ذلك العضو الصلاحيتين من جديد، أو أنشئ مفتاحًا بعضو لديه الصلاحيتان.
متى يحدث. توجد أداة أخرى في مساحة العمل بهذا الاسم. الرسالة تذكرها.
الحل. اختر اسمًا آخر.
متى يحدث. أرسل هذا المفتاح `Idempotency-Key` نفسه خلال آخر 24 ساعة، مع جسم طلب مختلف أو وكيل مختلف.
الحل. استخدم `Idempotency-Key` جديدًا لطلب جديد.
متى يحدث. الطلب الأول بهذا `Idempotency-Key` لم ينتهِ بعد.
الحل. انتظر قليلًا، ثم أعد المحاولة بالمفتاح نفسه لتحصل على نتيجته.
متى يحدث. جسم JSON أكبر من 100 كيلوبايت؛ يُرفض الطلب قبل فحص مفتاح API، فلا يحصل على صف في النشاط.
الحل. أرسل جسمًا أصغر؛ النص الطويل مكانه عدة طلبات.
متى يحدث. للطلب جسم وقيمة `Content-Type` فيه ليست `application/json`.
الحل. أرسل `Content-Type: application/json`.
متى يحدث. أرسل المفتاح أكثر من 20 طلبًا إلى نقطة النهاية هذه خلال 60 ثانية؛ وترويسة `Retry-After` تحمل عدد الثواني للانتظار.
الحل. انتظر عدد ثواني `Retry-After`، ثم أعد المحاولة.
متى يحدث. خطأ لم تصنّفه API.
الحل. تحقّق من الطلب، ثم أعد المحاولة بعد لحظة قصيرة؛ وتواصل مع الدعم إذا تكرر الخطأ.
متى يحدث. انقطاع مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
متى يحدث. انتهاء مهلة مؤقت داخل API.
الحل. أعد المحاولة بعد لحظة قصيرة.
curl -X POST "https://api.echonova.ai/v1/tools/webhook" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Order lookup","webhook":"string"}'{
"data": {
"id": "6650a1b2c3d4e5f6a7b8c9d0",
"name": "Order lookup",
"type": "webhook",
"description": "Finds an order by its number.",
"createdAt": "2026-11-01T10:00:00.000Z",
"updatedAt": "2026-11-01T10:00:00.000Z",
"webhook": {
"url": "https://api.example.com/orders/{orderId}",
"method": "GET",
"timeoutMs": 10000,
"connectionId": "6650a1b2c3d4e5f6a7b8c9d0",
"parameters": [
{
"location": "header",
"name": "orderId",
"dataType": "string",
"required": true,
"description": "Finds an order by its number.",
"valueType": "llm",
"secretId": "YOUR_SECRET_ID"
}
]
},
"openapi": {
"apiTitle": "Orders API",
"operationCount": 12,
"status": "ready",
"baseUrl": "https://api.example.com",
"includeOperations": [
"getOrder"
],
"authConnectionId": "YOUR_AUTH_CONNECTION_ID",
"error": null
},
"integration": {
"provider": "slack",
"key": "add_reaction"
}
},
"success": true,
"statusCode": 200,
"errorMessage": null
}