إشعارات Webhooks

تُعلم إشعارات webhooks خادمك بالأحداث لحظة وقوعها، فلا تحتاج إلى الاستعلام المتكرر. ترسل أوكتا فيديو طلب POST عبر HTTPS بجسم JSON إلى الرابط الذي تختاره، موقّعًا بسرّ لا يعرفه إلا أنت وأوكتا فيديو.

أضف نقطة استقبالنسخ رابط القسم

لكل مكتبة نقاط استقبال وأسرار خاصة بها. استخدم إرسال حدث تجريبي لتتحقق من نقطة الاستقبال قبل الإطلاق.

الأحداثنسخ رابط القسم

الطلبنسخ رابط القسم

Content-Type: application/json
OctaVideo-Event: video.ready
OctaVideo-Delivery: 2b7e4f1a-9c3d-4e8a-b5f6-0a1b2c3d4e5f
OctaVideo-Signature: t=1761384900,v1=5f2b9c0e7a4d…

{
  "id": "2b7e4f1a-9c3d-4e8a-b5f6-0a1b2c3d4e5f",
  "type": "video.ready",
  "created_at": "2026-10-25T09:35:00Z",
  "library_id": "0b8e5d3a-1c2f-4e6a-8b7d-9f0a1b2c3d4e",
  "data": {
    "video": {
      "id": "6f1c2b9e-4a7d-4f3e-9b8a-2d5c7e1f0a34",
      "title": "Lesson 1: Introduction",
      "encoding_status": "ready",
      "progress": 100,
      "duration_seconds": 754.2
    }
  }
}

يحمل data.video حقول جلب فيديو نفسها.

تحقّق من التوقيعنسخ رابط القسم

تحقّق دائمًا من OctaVideo-Signature قبل أن تثق بأي طلب:

1. قسّم الترويسة إلى t (طابع زمني بنظام Unix) وv1 (التوقيع).
2. احسب HMAC-SHA256 للنص t + "." + جسم الطلب الخام بسرّ التوقيع، بصيغة hex.
3. قارنه بـ v1 مقارنة ثابتة الزمن، وارفض الطلبات التي مضى على t فيها أكثر من 5 دقائق.

استخدم بايتات الجسم الخام: تحليل JSON ثم إعادة تسلسله يغيّرها ويُفسد التوقيع.

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/webhooks/octavideo', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('OctaVideo-Signature') ?? '';
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto
    .createHmac('sha256', process.env.OCTAVIDEO_WEBHOOK_SECRET)
    .update(`${parts.t}.${req.body}`)
    .digest('hex');

  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const valid =
    parts.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  if (!fresh || !valid) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  // Queue the work, then answer quickly.
  res.sendStatus(204);
});

تتضمّن حزم SDK دالة مساعدة تُجري هذه الفحوص عنك.

إعادة الإرسال والتكرارنسخ رابط القسم

• أجب بأي حالة 2xx خلال 10 ثوانٍ، وأنجز العمل البطيء بعد الإجابة، في طابور مهام مثلًا.
• أي إجابة أخرى، أو عدم الإجابة، يؤدي إلى إعادة الإرسال بمهلة متزايدة لمدة تصل إلى 24 ساعة.
• قد يصل الحدث نفسه أكثر من مرة، وقد تصل الأحداث بغير ترتيبها. استخدم id لتتجاهل الأحداث التي عالجتها من قبل، واجلب الفيديو حين تحتاج حالته الأحدث.
• تعرض Webhooks في لوحة التحكم كل عملية إرسال بحالتها والاستجابة، ويمكنك إعادة إرسال أي منها.