حدد webhook_url مع طلب التفريغ
أضفه إلى طلب رابط فيديو أو حجز رفع على أجزاء، أو كحقل في نموذج الرفع بطلب واحد. لا يمكن جمعه مع reuse_recent. راجع إعداد عنوان webhook قبل إضافته.
يناسب webhook العمل الذي يستمر بعد انتهاء الطلب الأصلي؛ مثل معالجة مقابلة مرفوعة أو بناء أرشيف حلقات أو تفريغ مجموعة فيديوهات. احفظ معرف التفريغ مع المهمة في تطبيقك حتى تربط الإشعار بالفعل الصحيح للمستخدم.
استخدم عنوان HTTPS النهائي القابل للوصول من الإنترنت، لا رابطا يعيد التوجيه. نتحقق من الوجهة عند الإنشاء والإرسال، ولا يصلح localhost لاستقبال الإشعارات. يرفع المثال أدناه ملفا يمكنك اختباره بتسجيل تملكه.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1اقبل التكرار دون تكرار الإجراء
تحتوي data على كائن التفريغ دون النص. استخدم data.id مع type لتمييز الحدث المكرر، ثم اجلب النص المكتمل عبر API.
قد يصل الطلب وتعالجه، ثم نعيده إذا تأخر ردك عن مهلة 10 ثوان. احفظ مفتاح منع التكرار، المكون من معرف التفريغ ونوع الحدث، قبل إرسال إشعار للمستخدم أو نشر محتوى. بعد التحقق من التوقيع، احفظ الحدث بشكل دائم أو أضفه إلى طابور، ثم أرسل 2xx بسرعة.
اجلب النص في مهمة خلفية باستخدام data.id. وإذا كان الحدث transcription.failed، افحص data.error وحدث حالة المهمة دون محاولة نشر نص غير موجود. أما الإلغاء فلا يرسل إشعارا؛ على مسار الإلغاء في تطبيقك تحديث حالته بنفسه.
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>
{
"type": "transcription.completed",
"created_at": "2026-10-13T09:30:04.000Z",
"data": {
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"object": "transcription",
"status": "completed",
"transcript_source": "speech_to_text",
"billed_minutes": 4,
"error": null
}
}احسب HMAC-SHA256 من الجسم الخام
وقع t ثم نقطة ثم جسم الطلب كما وصل، باستخدام HMAC-SHA256 وسر whsec_ كاملا. قارن التوقيع بزمن ثابت وارفض وقت الإرسال البعيد عن الوقت الحالي. اتبع دليل التحقق الكامل.
اقرأ الجسم الخام قبل أن يعالجه محلل JSON. إعادة تحويل كائن JSON إلى نص قد تغير المسافات أو ترتيب الحقول وتفشل التحقق. تحقق من الوقت وترويسة التوقيع، ثم قارن بصمتين متساويتي الطول بزمن ثابت. حلل JSON بعد نجاح التحقق فقط.
يفترض المثال المختصر أنك استخرجت t وv1 وتحققت منهما مسبقا. تتضمن الوثائق أمثلة كاملة في Node.js وPython بهامش زمني قدره 5 دقائق. لا تحذف بادئة whsec_ من السر. وتغيير سر الفريق يغير مفتاح الإرسال اللاحق فورا.
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const valid = v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));اختبر الفشل والتكرار قبل الاعتماد على الإشعار
اختبر حدث اكتمال وحدث فشل وتسليما مكررا. يجب ألا ينشر الاكتمال نفسه مرتين، وألا يبدأ الفشل مسار نشر يحتاج إلى نص. اختبر رفض التوقيع منفصلا عن أخطاء المعالجة في تطبيقك.
مهلة الرد 10 ثوان. لا تنتظر فهرسة بطيئة أو استدعاء نموذج قبل التأكيد. استخدم طابورا دائما في تطبيقك لإعادة الأعمال اللاحقة؛ محاولات تسليم webhook لا تحل محل إعادة معالجة مهامك.
الاستجابة خارج 2xx أو خطأ الاتصال أو انتهاء المهلة يؤدي إلى إعادة الإرسال بعد 2 ثم 4 ثم 8 ثم 16 ثم 32 دقيقة، حتى 6 محاولات إجمالا. لا نتبع إعادة التوجيه. سجل معرف المهمة ونوع الحدث وحالة التسليم، ولا تسجل سر التوقيع.
إذا انتهت المحاولات، راجع المعرفات المعروفة عبر جلب التفريغ. احتفظ بهذه المعرفات منذ الإنشاء؛ ينبغي ألا يكون وصول webhook دليلك الوحيد على وجود المهمة، وإلا قد تعيد إرسال التسجيل عند غياب إشعار.