Kılavuzlar

Geri çağırmalar

Görev geri çağırma teslimlerini güvenli şekilde alın ve doğrulayın.

Görev yaşam döngüsü olaylarını herkese açık bir HTTPS uç noktasında almak için geri çağırmaları kullanın. Yalnızca hesabınız için imzalanan teslimatların uygulama durumunu değiştirebilmesi amacıyla her geri çağırmayı JSON gövdesini işlemeden önce doğrulayın.

Bir geri çağırma URL'si yapılandırın

Görev oluştururken genel erişime açık bir HTTPS callback_url ekleyin. Olay gövdesi ve yaşam döngüsü durumları uç noktaya göre değişir; geri çağırma yükleri için ilgili uç noktanın API başvurusuna bakın.

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"
}

Bir Geri Çağırma Sırrı Oluşturun

Oturum açmak için Kimlik Doğrulama Kılavuzu‘nu takip edin, ardından API Anahtarları bölümünü açın ve Görevi oluşturan hesap için bir Geri Çağırma Gizli Anahtarı oluşturun. Değeri bir gizli yöneticisinde saklayın ve yalnızca geri çağırma alıcınızın erişimine açın. Bu bir API anahtarı değildir ve hiçbir zaman Task isteğinde gönderilmemelidir.

Gizli anahtar, söz konusu hesabın geri çağırmalarını imzalar. Anahtarı yenilemek sonraki teslimatların imzasını değiştireceğinden tüm geri çağırma alıcılarını hemen güncelleyin; her iki değeri de yalnızca uçuşta olan teslimatları işlemek için yeterli süre boyunca kullanılabilir tutun.

Geri çağırma imzasını doğrulayın

Her geri çağırma, Content-Type: application/json içeren bir HTTP POST isteğidir. RunAPI bu isteğe Authorization başlığı eklemez. Gövdeyi seri dışı bırakmadan önce şu başlıkları doğrulayın:

Başlık Anlam X-Callback-Id Bu iletim denemesine ait benzersiz tanımlayıcı. X-Callback-Timestamp İletimin imzalandığı andaki Unix zaman damgası (saniye cinsinden). X-Callback-Signature Base64 ile kodlanmış HMAC-SHA-256 imzası.

İmzalı değeri, değiştirilmemiş istek gövdesi baytlarını kullanarak tam olarak aşağıdaki şekilde oluşturun:

TEXT

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

Geri Çağırma Sırrını Base64 ile çözün, bu değer üzerinden HMAC-SHA-256 hesaplayın, sonucu Base64 ile kodlayın ve zamanlama güvenli karşılaştırma kullanarak X-Callback-Signature ile karşılaştırın. Doğrulamadan önce JSON’u ayrıştırıp yeniden serileştirmeyin.

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);
}

Çerçevenin ham istek gövdesi dizesini rawBody parametresine geçirin; ayrıştırılmış veriler üzerinde JSON.stringify çağırmayın.

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 çerçevenizin aldığı ham istek gövdesi dizesini olduğu gibi raw_body olarak geçirin.

Teslimatları güvenli biçimde işleyin

2xx yanıtını yalnızca geri çağırma işleme kabul edildikten sonra döndürün. 2xx dışı bir yanıt veya iletim hatası sonrasında teslimat en fazla 10 kez denenir.
15 saniye içinde yanıt verin. Daha yavaş işleri HTTP yanıtını engellemek yerine doğrulamadan sonra kuyruğa alın.
Eksik imza başlıkları, geçersiz imza veya alıcınızın tanımladığı tolerans penceresi dışında kalan bir zaman damgası içeren geri çağırmaları reddedin.

Doğrulamada sorun giderme

İmza uyuşmazlığı: Geri çağırma Gizlisinin Görevle aynı hesaba ait olduğunu doğrulayın, Base64 ile çözün ve ayrıştırılmış JSON yerine özgün gövdeyi imzalayın.
İmza başlıkları eksik: Durum değişiklikleri için geri çağırmalara güvenmeden önce bir Geri Çağırma Gizlisi oluşturun.
Zaman damgası reddedildi: Alıcının saatini senkronize edin ve dağıtımınıza uygun bir tolerans kullanın.

Kurulum ve yaşam döngüsü rehberliği için Görev API’si Hızlı başlangıç bölümüne dönün.