المطورون / Tools

إنشاء أداة webhook

POST https://api.echonova.ai/v1/tools/webhook

تنشئ أداة تستدعي عنوان URL عامًا واحدًا بصيغة https مع المعاملات التي تحددها. تُشار قيم الترويسات السرية وروابط المصادقة بمعرّفاتها، ويُرفض أي نص عادي يبدو كبيانات اعتماد. يأخذ الطلب الاستدعاء تحت `webhook.target.url`، ويعرضه الرد باسم `webhook.url`. أرسل `Idempotency-Key` لإعادة المحاولة بأمان. الحد: 20 طلبًا في الدقيقة لكل مفتاح. تُشار الأسرار بمعرّفها من `GET /v1/secrets`، ولا تُدخل قيمها إلا في خزنة البوابة. استخدام هذه النقطة مجاني. يحتاج المفتاح إلى النطاق `tools:write`.

Headers

Authorization string مطلوب

كلمة ⁦Bearer⁩ ثم مسافة ثم مفتاح ⁦API⁩ الذي يبدأ بـ ⁦ek_⁩. أنشئ المفاتيح في البوابة من المطورون، ثم مفاتيح واجهة برمجة التطبيقات.

Idempotency-Key string اختياري

اختياري. كرّر المفتاح نفسه خلال 24 ساعة لإعادة المحاولة بأمان: تعود النتيجة الأولى، ولا يُنشأ شيء مرتين. الطلب الجديد يحتاج إلى مفتاح جديد.

متن الطلب

application/json

name string مطلوب

اسم الأداة، ويجب أن يكون فريدًا في مساحة العمل.

من 1 إلى 120 حرفًا
description string اختياري

وظيفة الأداة.

حتى 500 حرفًا
webhook object مطلوب

الاستدعاء الذي تنفذه الأداة.

الاستجابة

200 application/json كل استجابة تستخدم هذا الغلاف.

data object

النتيجة.

success boolean

قيمته ⁦true⁩ عند نجاح الطلب.

statusCode integer

يكرر رمز حالة ⁦HTTP⁩.

errorMessage string or null

قيمته ⁦null⁩ عند النجاح.

الأخطاء

الغلاف نفسه، مع ⁦success⁩ بقيمة ⁦false⁩ و ⁦data⁩ بقيمة ⁦null⁩. كل الأخطاء

POST /v1/tools/webhook

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
}