عمليات الاستدعاء
استقبال عمليات استدعاء المهام والتحقق منها بأمان.
استخدم عمليات الاستدعاء لتلقي أحداث دورة حياة Task على نقطة نهاية HTTPS عامة. تحقق من صحة كل عملية استدعاء قبل معالجة نص JSON الخاص بها حتى لا تتمكن إلا عمليات التسليم الموقّعة لحسابك من تغيير حالة التطبيق.
إعداد عنوان URL لعملية الاستدعاء
أضف callback_url عبر HTTPS عام حين تنشئ مهمة. يعتمد نص الحدث
وحالات دورة الحياة على نقطة النهاية؛ راجع مرجع API الخاص بها
للاطلاع على حمولات الاستدعاء.
{
"model": "flux-2-pro-text-to-image",
"prompt": "A product photograph on a clean studio background",
"callback_url": "https://your-domain.com/webhooks/runapi"
}
إنشاء سرّ عملية الاستدعاء
اتبع دليل المصادقة لتسجيل الدخول، ثم افتح API Keys وأنشئ Callback Secret للحساب الذي يُنشئ المهمة. احتفظ بالقيمة في مدير الأسرار وأتِح الوصول إليها لمستقبل الاستدعاء فقط. إنه ليس مفتاح API ويجب ألا يُرسَل أبداً في طلب مهمة Task.
يوقّع السر عمليات الاستدعاء لذلك الحساب. يُغيّر تدويره التوقيع للتسليمات اللاحقة، لذا حدّث كل مُستقبِل لعمليات الاستدعاء فورًا واحتفظ بكلتا القيمتين متاحتَين فقط لوقت كافٍ للتعامل مع التسليمات الجارية.
التحقق من توقيع عملية الاستدعاء
كل استدعاء هو طلب HTTP POST يحمل Content-Type: application/json.
لا تضيف RunAPI رأس Authorization إلى هذا الطلب. تحقق من هذه الرؤوس قبل إلغاء تسلسل الجسم:
X-Callback-Id
معرّف فريد لمحاولة التسليم هذه.
X-Callback-Timestamp
طابع زمني Unix بالثواني يحدد وقت توقيع التسليم.
X-Callback-Signature
توقيع HMAC-SHA-256 مشفر بـ Base64.
أنشئ القيمة الموقَّعة بالضبط على النحو التالي، باستخدام بايتات جسم الطلب غير المعدَّلة:
X-Callback-Id + "." + X-Callback-Timestamp + "." + raw request body
قم بفكّ ترميز Callback Secret بـ Base64، واحسب HMAC-SHA-256 على تلك
القيمة، ثم قم بترميز النتيجة بـ Base64، وقارنها مع
X-Callback-Signature باستخدام مقارنة آمنة زمنياً. لا تقم بتحليل
JSON وإعادة تسلسله قبل التحقق.
JavaScript
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyCallback({headers, rawBody, callbackSecret}) {
const callbackId = headers["x-callback-id"];
const timestamp = Number(headers["x-callback-timestamp"]);
const signature = headers["x-callback-signature"];
if (!callbackId || !signature || !Number.isSafeInteger(timestamp)) return false;
if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
const signedContent = `${callbackId}.${timestamp}.${rawBody}`;
const expected = createHmac("sha256", Buffer.from(callbackSecret, "base64"))
.update(signedContent, "utf8")
.digest();
const received = Buffer.from(signature, "base64");
return expected.length === received.length && timingSafeEqual(expected, received);
}
مرّر سلسلة نص جسم الطلب الخام من إطار العمل إلى rawBody؛ ولا تستدعِ
JSON.stringify على البيانات المحللة.
Python
import base64
import hashlib
import hmac
import time
def verify_callback(headers, raw_body, callback_secret):
callback_id = headers.get("X-Callback-Id")
timestamp = headers.get("X-Callback-Timestamp")
signature = headers.get("X-Callback-Signature")
if not callback_id or not timestamp or not signature:
return False
try:
timestamp = int(timestamp)
secret = base64.b64decode(callback_secret, validate=True)
received = base64.b64decode(signature, validate=True)
except (ValueError, TypeError):
return False
if abs(time.time() - timestamp) > 300:
return False
signed_content = f"{callback_id}.{timestamp}.{raw_body}".encode("utf-8")
expected = hmac.new(secret, signed_content, hashlib.sha256).digest()
return hmac.compare_digest(expected, received)
مرّر سلسلة نص جسم الطلب الخام التي استقبلها إطار عمل HTTP لديك
كـ raw_body.
معالجة عمليات التسليم بأمان
- أرسل استجابة
2xxفقط بعد قبول معالجة طلب الاستدعاء. في حالة الاستجابة غير2xxأو فشل النقل، تُحاوَل إعادة التسليم حتى 10 مرات. - استجب في غضون 15 ثانية. أضف العمل الأبطأ إلى قائمة انتظار بعد التحقق بدلاً من تعطيل استجابة HTTP.
- ارفض عمليات الاستدعاء التي تفتقر إلى ترويسات التوقيع، أو تحمل توقيعاً غير صالح، أو تحتوي على طابع زمني خارج نافذة التسامح التي يحددها المستقبل.
استكشاف أخطاء التحقق وإصلاحها
- عدم تطابق التوقيع: تأكد من أن Callback Secret ينتمي إلى الحساب ذاته الخاص بالمهمة، وفكّ ترميزه بـ Base64، ووقّع النص الأصلي للطلب لا JSON المُحلَّل.
- رؤوس التوقيع مفقودة: أنشئ Callback Secret قبل الاعتماد على عمليات الاستدعاء لتغييرات الحالة.
- رُفض الطابع الزمني: زامن ساعة المستقبِل واستخدم هامش تسامح مناسب لبيئة نشرك.
للاطلاع على إرشادات الإعداد ودورة الحياة، ارجع إلى البدء السريع لـ Task API .