Hozz létre aláírt Rivya API webhook endpointokat, ellenőrizd a kézbesítési aláírásokat, vizsgáld meg a kézbesítési próbálkozásokat, és küldj biztonságos teszteseményeket.

Akkor használj API webhookokat, amikor az integrációdnak arra van szüksége, hogy a Rivya értesítse a szerveredet, miután egy Public API generálás végállapotba ér.

A GET /api/v1/generations/{taskId} polling továbbra is támogatott. A webhookok aláírt callbackeket adnak azokhoz az éles rendszerekhez, amelyek eseménykézbesítést preferálnak.

Szükséges scope

A webhookkezeléshez olyan API-kulcs kell, amely tartalmazza:

webhooks:manage

A Beállításokban létrehozott új kulcsok alapértelmezés szerint tartalmazzák ezt a scope-ot.

Endpoint létrehozása

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

A válasz csak egyszer tartalmazza a signing_secret értéket:

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

Tárold a teljes titkot a szervereden. Ha elveszíted, hívd meg a rotate endpointot, és frissítsd a fogadó oldalt.

Az endpoint URL-eknek HTTPS-t kell használniuk. A Rivya elutasítja a hitelesítő adatokat, fragmenteket, localhost neveket, helyi hálózati címeket, privát IP-tartományokat, loopback címeket és fenntartott címeket tartalmazó URL-eket.

A Rivya mindig ezt küldi:

POST
Content-Type: application/json
nincs egyedi, felhasználó által vezérelt request header
nincs automatikus redirectkövetés
rövid kézbesítési timeout

Események

Jelenlegi eseménytípusok:

generation.succeeded
generation.failed

A webhook payloadok ugyanazt a nyilvános generálási szerializálót használják, mint az állapot 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
    }
  }
}

Kézbesítési headerek

Minden kézbesítés tartalmazza:

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

Aláírási bemenet:

${timestamp}.${rawBody}

Algoritmus:

HMAC-SHA256 with the endpoint signing secret

Utasítsd el az elavult timestampet tartalmazó kéréseket. Az ötperces tolerancia praktikus alapértelmezés.

JavaScript ellenőrzés

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 ellenőrzés

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)

Endpointok kezelése

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

A DELETE /api/v1/webhooks/{endpointId} letiltja az endpointot. Nem törli a kézbesítési előzményeket.

Kézbesítési rekordok

Legutóbbi események listázása:

GET /api/v1/webhook-events

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

Egy endpoint kézbesítési próbálkozásainak listázása:

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

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

A kézbesítési rekordok tartalmazzák az állapotot, HTTP státuszt, próbálkozásszámot, request id-t, időtartamot, csonkított válaszrészletet és nyilvános hibamezőket.

Tesztesemény

Küldj biztonságos tesztpayloadot:

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

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

A tesztesemény webhook.test típust használ. Nem hoz létre generálási feladatot, nem fogyaszt kreditet, és nem tartalmaz valódi eredmény URL-t.

Újrapróbálkozási szabályzat

A Rivya a HTTP 2xx választ sikernek tekinti.

Hibának számítanak a hálózati hibák, timeout, redirect válaszok és nem 2xx válaszok. A Rivya legfeljebb öt próbálkozást végez:

azonnal
1 perc múlva
5 perc múlva
30 perc múlva
2 óra múlva

Az utolsó próbálkozás után az esemény failed állapotba kerül.

A webhook kézbesítési hibái nem módosítják a generálás állapotát, krediteket, visszatérítéseket vagy feladatelőzményeket.

Biztonsági ellenőrzőlista

Ellenőrizd a HMAC aláírást az üzleti logika feldolgozása előtt.
Utasítsd el az elavult timestampet.
A teszteseményeket kezeld külön a generálási eseményektől.
Ne logolj teljes aláírási titkokat.
Csak akkor adj vissza 2xx választ, miután a fogadó oldal elfogadta az eseményt.
Tartsd meg a pollingot tartalék egyeztetési módként.

API webhookok