إعداد Webhook

Webhook هو عنوان HTTPS تملكه، تستدعيه إيكونوڤا عندما تنتهي مهمة غير متزامنة، أو عندما يتجاوز مفتاح API حد الرصيد الخاص به. تنشئه في البوابة، وتختار الأحداث التي يشترك بها، وتحتفظ بسر التوقيع حتى يتحقق خادمك من كل تسليم.

ما تحتاج إليه

• حساب في إيكونوڤا ومساحة عمل. سجّل الدخول من /auth/sign-in.
• صلاحية مالك مساحة العمل، وتشمل developer_api.manage لإنشاء Webhooks وتعديلها وحذفها. عرض القائمة يحتاج إلى developer_api.view.
• نقطة نهاية عامة تقبل طلبات POST بجسم JSON عبر https.
• مفتاح API، إذا أردت أحداث المهام. تُعلَن فقط المهام التي بدأت بمفتاح API. راجع الحصول على مفتاح API.

الخطوات

الخطوة 1: افتح تبويب خطافات الويب

انتقل إلى /developers?tab=webhooks، أو افتح المطورون في البوابة، ثم اختر تبويب خطافات الويب. تظهر هنا Webhooks التي أنشأتها. في مساحة عمل فارغة تظهر العبارة لا توجد خطافات ويب بعد مع النص "أضف نقطة النهاية الأولى لاستقبال إشعارات الأحداث."

الخطوة 2: أنشئ Webhook

اختر إضافة نقطة نهاية ثم املأ النافذة.

اختر إنشاء. تُغلق النافذة ويظهر Webhook الجديد في أعلى القائمة.

الخطوة 3: احفظ سر التوقيع

كل Webhook جديد يحصل على سر توقيع. يبدأ السر بـ whsec_. بعد أن تختار إنشاء، تعرض النافذة السر مرة واحدة، مع زر نسخ وتحذير بالأحمر. اختر نسخ واحفظ السر. ثم اختر تم لإغلاق النافذة. لا يمكن عرض السر مرة أخرى. يعيده طلب الإنشاء أيضًا مرة واحدة في الحقل signingSecret. بعد ذلك تعرض البوابة وكل استجابة API أول 12 حرفًا فقط، في الحقل signingSecretPrefix.

الخطوة 4: أرسل حدثًا تجريبيًا

للتأكد من أن نقطة النهاية تعمل، ابدأ مهمة غير متزامنة بمفتاح API واتركها تنتهي:

curl -X POST https://api.echonova.ai/v1/text-to-speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Webhook test", "voiceId": "VOICE_ID"}'

import requests

response = requests.post(
    "https://api.echonova.ai/v1/text-to-speech",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"text": "Webhook test", "voiceId": "VOICE_ID"},
)
print(response.json())

const response = await fetch('https://api.echonova.ai/v1/text-to-speech', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ text: 'Webhook test', voiceId: 'VOICE_ID' }),
});
console.log(await response.json());

عند اكتمال المهمة، يستلم كل Webhook مفعّل مشترك في job.completed طلب POST واحدًا. صيغة الطلب والجسم في أحداث Webhook، والاستجابة التي يجب أن يعيدها خادمك في التسليم وإعادة المحاولة والفشل.

اجعل نقطة النهاية صحيحة

رُدّ بسرعة وعبر HTTPS. ينتظر كل تسليم 10 ثوانٍ لردك، والتوقيع يصل في header، لذلك تكلّفك نقطة النهاية البطيئة إعادات محاولة زائدة. لا تُقبل نقاط النهاية عبر HTTP العادي.

موصى به

• https://api.example.com/echonova/webhook يتحقق من التوقيع، ويعيد 200 فورًا، ثم يعالج الحدث بعد ذلك.

أقل فاعلية

• https://203.0.113.10:8443/hook يُنزّل الصوت ويكتب في قاعدة البيانات قبل أن يرد.

ماذا يحدث بعد ذلك

• تعرض القائمة لكل Webhook: الاسم، الأحداث المُشترك بها، المعرّف مُقنّعًا، نقطة النهاية، وشارة الحالة وقيمتها مُفعَّل أو معطّل.
• المفتاح في الصف يفعّل Webhook أو يعطّله. تؤكد رسالة منبثقة تم التحديث مع النص "خطاف الويب مُفعَّل" أو "خطاف الويب مُعطَّل". لا يستلم Webhook المعطّل أي شيء حتى تفعّله من جديد.
• تفتح قائمة الصف الإجراءات: تعديل، نسخ معرّف خطاف الويب، وحذف.
• تعديل يفتح النافذة نفسها بعنوان تعديل خطاف الويب، وبزر حفظ التغييرات. تستطيع تغيير الاسم ورابط نقطة النهاية والأحداث وحالة التفعيل. لا يتغير سر التوقيع.
• حذف يفتح نافذة حذف خطاف الويب، وتسأل: هل تريد حذف خطاف الويب "NAME"؟ لا يمكن التراجع عن هذا الإجراء. يُستبدل NAME باسم Webhook لديك. اختر حذف للتأكيد. يتوقف Webhook عن استلام الأحداث فورًا.
• إذا فشلت 5 تسليمات متتالية، يُعطَّل Webhook تلقائيًا. أصلح نقطة النهاية، ثم فعّله من جديد. يعيد التفعيل عداد الإخفاقات إلى صفر.

الحدود

استكشاف المشكلات

أدخل رابطًا صالحًا يبدأ بـ https://.

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

subscribedEvents must contain at least 1 elements

اخترت إنشاء دون تحديد أي حدث في أنواع الأحداث. حدّد حدثًا واحدًا على الأقل وحاول مرة أخرى.

endpointUrl must be a URL address

رفضت الواجهة البرمجية نقطة النهاية. تحتاج إلى بروتوكول ومضيف. تحقق من المسافات أو من غياب ://.

تعذّر إنشاء خطاف الويب. يُرجى المحاولة مرة أخرى.

لم تستطع البوابة قراءة رسالة خطأ من الواجهة البرمجية. أعد تحميل الصفحة وحاول مرة أخرى. إذا استمر الخطأ، فتحقق من أن دورك ما زال يملك developer_api.manage.

Webhook not found

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

تحوّل خطاف الويب إلى معطّل من تلقاء نفسه

فشلت 5 تسليمات متتالية بعد كل المحاولات. اجعل نقطة النهاية تعيد حالة 2xx خلال 10 ثوانٍ، ثم فعّل Webhook من جديد. راجع التسليم وإعادة المحاولة والفشل.

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

هل أستطيع رؤية سر التوقيع مرة أخرى؟

لا. يُعاد السر مرة واحدة في استجابة الإنشاء. احذف Webhook وأنشئ واحدًا جديدًا للحصول على سر جديد.

هل يغيّر تعديل رابط نقطة النهاية السر؟

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

هل تُطلق استدعاءات متزامنة أحداث المهام؟

لا. يُرسل job.completed وjob.failed للمهام غير المتزامنة فقط، وفقط للمهام التي بدأت بمفتاح API. لا تُعلَن المهام التي بدأت من البوابة.

هل Webhooks لكل مفتاح API أم لكل مساحة عمل؟

لكل مساحة عمل. يستلم كل Webhook مفعّل في مساحة العمل يشترك في الحدث، أيًّا كان مفتاح API الذي أنتج المهمة.

من يستطيع إدارة Webhooks؟

مالك مساحة العمل، الذي يملك دوره developer_api.manage.

ذو صلة

• أحداث Webhook
• التحقق من توقيع Webhook
• التسليم وإعادة المحاولة والفشل
• الحصول على مفتاح API
• إنشاء كلام من نص