İmzalı Rivya API webhook endpoint'leri oluşturun, delivery imzalarını doğrulayın, delivery denemelerini inceleyin ve güvenli test olayları gönderin.

Entegrasyonunuz bir Public API generation terminal duruma ulaştıktan sonra Rivya'nın sunucunuzu bilgilendirmesine ihtiyaç duyuyorsa API webhooks kullanın.

GET /api/v1/generations/{taskId} ile polling hâlâ desteklenir. Webhooks, olay delivery tercih eden production sistemler için imzalı callback'ler ekler.

Gerekli Scope

Webhook yönetimi şu scope'a sahip bir API anahtarı gerektirir:

webhooks:manage

Settings içinde oluşturulan yeni anahtarlar bu scope'u varsayılan olarak içerir.

Endpoint Oluşturma

POST /api/v1/webhooks

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://example.com/rivya/webhook",
    "event_types": ["generation.succeeded", "generation.failed"]
  }'

Yanıt signing_secret değerini yalnızca bir kez içerir:

{
  "id": "whend_...",
  "object": "webhook_endpoint",
  "name": "Production webhook",
  "url": "https://example.com/rivya/webhook",
  "event_types": ["generation.succeeded", "generation.failed"],
  "status": "active",
  "secret_preview": "whsec_12...abc123",
  "signing_secret": "whsec_...",
  "last_success_at": null,
  "last_failure_at": null,
  "failure_count": 0,
  "created_at": "2026-05-11T00:00:00.000Z",
  "updated_at": "2026-05-11T00:00:00.000Z",
  "disabled_at": null,
  "revoked_at": null
}

Tam secret değerini sunucunuzda saklayın. Kaybederseniz rotate endpoint'ini çağırın ve alıcınızı güncelleyin.

URL Kuralları

Endpoint URL'leri HTTPS olmalıdır. Rivya credentials, fragment, localhost adları, local network adresleri, private IP aralıkları, loopback adresleri ve reserved adresler içeren URL'leri reddeder.

Rivya her zaman şunları gönderir:

POST
Content-Type: application/json
kullanıcı kontrollü custom request header yok
otomatik redirect takip etme yok
kısa delivery timeout

Olaylar

Geçerli olay türleri:

generation.succeeded
generation.failed

Webhook payload'ları status endpoint'iyle aynı public generation serializer'ını kullanır.

{
  "id": "evt_...",
  "type": "generation.succeeded",
  "api_version": "2026-05-11",
  "created_at": "2026-05-11T00:00:00.000Z",
  "data": {
    "generation": {
      "id": "task_public_id",
      "status": "succeeded",
      "model": "z-image",
      "reserved_credits": 1,
      "final_credits": 1,
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:01:00.000Z",
      "result": {
        "primary_url": "https://...",
        "urls": ["https://..."]
      },
      "error": null
    }
  }
}

Delivery Header'ları

Her delivery şunları içerir:

Rivya-Webhook-Id: evt_...
Rivya-Webhook-Timestamp: 1778467200
Rivya-Webhook-Signature: v1=<hex-hmac-sha256>
Rivya-Webhook-Attempt: 1
Rivya-Webhook-Endpoint-Id: whend_...
Rivya-Request-Id: req_...

İmza input'u:

${timestamp}.${rawBody}

Algoritma:

HMAC-SHA256 with the endpoint signing secret

Eski timestamp'li istekleri reddedin. Beş dakikalık tolerans pratik bir varsayılandır.

JavaScript Doğrulama

import crypto from "node:crypto";

function verifyRivyaWebhook({ rawBody, headers, signingSecret }) {
  const timestamp = headers["rivya-webhook-timestamp"];
  const signature = headers["rivya-webhook-signature"] || "";
  const actual = signature.split(",").find((part) => part.startsWith("v1="))?.slice(3);
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  if (!actual) return false;
  return crypto.timingSafeEqual(Buffer.from(actual, "hex"), Buffer.from(expected, "hex"));
}

Python Doğrulama

import hmac
import hashlib

def verify_rivya_webhook(raw_body: str, headers: dict, signing_secret: str) -> bool:
    timestamp = headers.get("rivya-webhook-timestamp", "")
    signature = headers.get("rivya-webhook-signature", "")
    actual = next((part[3:] for part in signature.split(",") if part.startswith("v1=")), "")
    expected = hmac.new(
        signing_secret.encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return bool(actual) and hmac.compare_digest(actual, expected)

Endpoint'leri Yönetme

GET /api/v1/webhooks
GET /api/v1/webhooks/{endpointId}
PATCH /api/v1/webhooks/{endpointId}
DELETE /api/v1/webhooks/{endpointId}
POST /api/v1/webhooks/{endpointId}/rotate-secret

curl https://rivya.ai/api/v1/webhooks \
  -H "Authorization: Bearer rvya_sk_..."

curl https://rivya.ai/api/v1/webhooks/whend_... \
  -H "Authorization: Bearer rvya_sk_..."

curl -X PATCH https://rivya.ai/api/v1/webhooks/whend_... \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

curl -X POST https://rivya.ai/api/v1/webhooks/whend_.../rotate-secret \
  -H "Authorization: Bearer rvya_sk_..."

DELETE /api/v1/webhooks/{endpointId} endpoint'i devre dışı bırakır. Delivery geçmişini silmez.

Delivery Kayıtları

Son olayları listeleyin:

GET /api/v1/webhook-events

curl https://rivya.ai/api/v1/webhook-events \
  -H "Authorization: Bearer rvya_sk_..."

Bir endpoint için delivery denemelerini listeleyin:

GET /api/v1/webhooks/{endpointId}/deliveries

curl https://rivya.ai/api/v1/webhooks/whend_.../deliveries \
  -H "Authorization: Bearer rvya_sk_..."

Delivery kayıtları status, HTTP status, attempt number, request id, duration, kısaltılmış response snippet ve public error alanlarını içerir.

Test Olayı

Güvenli bir test payload'u gönderin:

POST /api/v1/webhooks/{endpointId}/test

curl -X POST https://rivya.ai/api/v1/webhooks/whend_.../test \
  -H "Authorization: Bearer rvya_sk_..."

Test olayı webhook.test kullanır. Generation görevi oluşturmaz, kredi tüketmez ve gerçek sonuç URL'si içermez.

Yeniden Deneme Politikası

Rivya HTTP 2xx değerini başarı olarak kabul eder.

Hata durumları ağ hatalarını, timeout'ları, redirect response'larını ve 2xx olmayan response'ları içerir. Rivya en fazla beş deneme yapar:

hemen
1 dakika sonra
5 dakika sonra
30 dakika sonra
2 saat sonra

Son denemeden sonra olay failed olarak işaretlenir.

Webhook delivery hataları generation durumunu, kredileri, iadeleri veya görev geçmişini değiştirmez.

Güvenlik Kontrol Listesi

İş mantığını ayrıştırmadan önce HMAC imzasını doğrulayın.
Eski timestamp'leri reddedin.
Test olaylarını generation olaylarından ayrı ele alın.
Tam signing secret'ları loglamayın.
Alıcı olayı kabul ettikten sonra 2xx döndürün.
Mutabakat için polling'i fallback olarak tutun.

API Webhooks