تخطَّ إلى المحتوى
الأدلة
الأدلة

عمليات الاستدعاء

استقبال عمليات استدعاء المهام والتحقق منها بأمان.

استخدم عمليات الاستدعاء لتلقي أحداث دورة حياة Task على نقطة نهاية HTTPS عامة. تحقق من صحة كل عملية استدعاء قبل معالجة نص JSON الخاص بها حتى لا تتمكن إلا عمليات التسليم الموقّعة لحسابك من تغيير حالة التطبيق.

إعداد عنوان URL لعملية الاستدعاء

أضف callback_url عبر HTTPS عام حين تنشئ مهمة. يعتمد نص الحدث وحالات دورة الحياة على نقطة النهاية؛ راجع مرجع API الخاص بها للاطلاع على حمولات الاستدعاء.

JSON
{
  "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.

أنشئ القيمة الموقَّعة بالضبط على النحو التالي، باستخدام بايتات جسم الطلب غير المعدَّلة:

TEXT
X-Callback-Id + "." + X-Callback-Timestamp + "." + raw request body

قم بفكّ ترميز Callback Secret بـ Base64، واحسب HMAC-SHA-256 على تلك القيمة، ثم قم بترميز النتيجة بـ Base64، وقارنها مع X-Callback-Signature باستخدام مقارنة آمنة زمنياً. لا تقم بتحليل JSON وإعادة تسلسله قبل التحقق.

JavaScript

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

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 .