Webhooks

احصل على إشعارات فورية عند اكتمال المهام أو فشلها

نظرة عامة

تتيح لك Webhooks استقبال نداءات HTTP عند اكتمال مهام إنشاء الصور أو مقاطع الفيديو. بدلاً من الاستعلام المتكرر عن النتائج، يمكنك إعداد نقطة نهاية Webhook لتلقي إشعارات تلقائية.

الأحداث المتاحة

task.completedيتم تشغيله عند اكتمال المهمة بنجاح

task.failedيتم تشغيله عند فشل مهمة

GET/api/v1/webhooks

سرد جميع تكوينات Webhook الخاصة بك

الرد

{
  "success": true,
  "data": [
    {
      "id": 1,
      "url": "https://your-server.com/webhook",
      "events": ["job.completed", "job.failed"],
      "status": "active"
    }
  ]
}

POST/api/v1/webhooks

إنشاء نقطة نهاية ويب هوك جديدة

نص الطلب

{
  "url": "https://your-server.com/webhook",
  "events": ["job.completed", "job.failed"],
  "secret_key": "your-secret-key"
}

حقول الجسم

معامل	النوع	مطلوب	وصف
url	string	مطلوب	عنوان نهاية نقطة الويب هوك الخاص بك
events	string[]	مطلوب	الأحداث التي يمكن الاشتراك فيها
secret_key	string	اختياري	سرّ للتحقق من التوقيع

الرد

{
  "success": true,
  "data": {
    "id": 1,
    "url": "https://your-server.com/webhook",
    "events": ["job.completed", "job.failed"],
    "status": "active"
  }
}

DELETE/api/v1/webhooks/{id}

حذف نقطة نهاية الويب هوك

الرد

{
  "success": true,
  "data": { "id": 1 }
}

حمولة Webhook

عندما يحدث حدث، سنرسل طلب POST إلى عنوان URL الخاص بويب هوك الخاص بك مع الحمولة التالية:

رؤوس الصفحات

رأس الصفحة	وصف
X-Webhook-Timestamp	طابع زمني يونكس للطلب
X-Webhook-Signature	توقيع HMAC-SHA256 للتحقق من المصادقة

مثال الحمولة

{
  "event": "job.completed",
  "task_id": "task_xxx",
  "task_type": "image",
  "status": "completed",
  "data": {
    "url": "https://cdn.example.com/image.png",
    "credits_charged": 6
  },
  "timestamp": "2024-12-23T10:00:00Z"
}

التحقق من التوقيع

التحقق من أصالة webhook باستخدام HMAC-SHA256

const crypto = require('crypto');

function verifySignature(payload, signature, secret, timestamp) {
  const message = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return `v1=${expectedSig}` === signature;
}