Erstelle signierte Rivya API-Webhook-Endpoints, verifiziere Delivery-Signaturen, prüfe Delivery-Versuche und sende sichere Test-Events.

Nutze API Webhooks, wenn deine Integration von Rivya benachrichtigt werden soll, nachdem eine Public-API-Generation einen terminalen Zustand erreicht.

Polling über GET /api/v1/generations/{taskId} wird weiterhin unterstützt. Webhooks ergänzen signierte Callbacks für Produktionssysteme, die Event-Delivery bevorzugen.

Erforderlicher Scope

Webhook-Verwaltung benötigt einen API Key mit:

webhooks:manage

Neue Keys, die in den Einstellungen erstellt werden, enthalten diesen Scope standardmäßig.

Endpoint erstellen

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

Die Antwort enthält signing_secret nur einmal:

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

Speichere das vollständige Secret auf deinem Server. Wenn du es verlierst, rufe den Rotate-Endpoint auf und aktualisiere deinen Receiver.

URL-Regeln

Endpoint-URLs müssen HTTPS sein. Rivya weist URLs mit Credentials, Fragmenten, localhost-Namen, lokalen Netzwerkadressen, privaten IP-Ranges, Loopback-Adressen und reservierten Adressen zurück.

Rivya sendet immer:

POST
Content-Type: application/json
keine benutzergesteuerten Custom Request Headers
kein automatisches Folgen von Redirects
ein kurzes Delivery-Timeout

Events

Aktuelle Event-Typen:

generation.succeeded
generation.failed

Webhook-Payloads verwenden denselben öffentlichen Generation Serializer wie der Status-Endpoint.

{
  "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 Headers

Jede Delivery enthält:

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_...

Signature-Input:

${timestamp}.${rawBody}

Algorithmus:

HMAC-SHA256 with the endpoint signing secret

Weise Requests mit veralteten Timestamps zurück. Eine Toleranz von fünf Minuten ist ein praktischer Standard.

JavaScript-Verifizierung

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-Verifizierung

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)

Endpoints verwalten

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} deaktiviert den Endpoint. Es löscht keine Delivery-History.

Delivery Records

Aktuelle Events auflisten:

GET /api/v1/webhook-events

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

Delivery-Versuche für einen Endpoint auflisten:

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

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

Delivery Records enthalten Status, HTTP-Status, Versuchszahl, Request-ID, Dauer, gekürzten Response-Ausschnitt und öffentliche Fehlerfelder.

Test-Event

Sende ein sicheres Test-Payload:

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

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

Das Test-Event verwendet webhook.test. Es erstellt keinen Generation-Task, verbraucht keine Credits und enthält keine echte Result-URL.

Retry-Policy

Rivya behandelt HTTP 2xx als Erfolg.

Fehler umfassen Netzwerkfehler, Timeout, Redirect-Antworten und nicht-2xx-Antworten. Rivya versucht bis zu fünfmal erneut:

sofort
nach 1 Minute
nach 5 Minuten
nach 30 Minuten
nach 2 Stunden

Nach dem letzten Versuch wird das Event als failed markiert.

Webhook-Delivery-Fehler ändern Generation-Status, Credits, Rückerstattungen oder Task-History nicht.

Sicherheitscheckliste

Verifiziere die HMAC-Signatur, bevor du Business-Logik parst.
Weise veraltete Timestamps zurück.
Behandle Test-Events getrennt von Generation-Events.
Logge keine vollständigen Signing Secrets.
Gib 2xx erst zurück, nachdem dein Receiver das Event akzeptiert hat.
Behalte Polling als Fallback für Reconciliation bei.

API Webhooks