Opprett signerte Rivya API-webhook-endepunkter, verifiser leveringssignaturer, inspiser leveringsforsøk og send trygge testhendelser.

Bruk API-webhooks når integrasjonen din trenger at Rivya varsler serveren din etter at en Public API-generering når en terminal tilstand.

Polling med GET /api/v1/generations/{taskId} støttes fortsatt. Webhooks legger til signerte callbacks for produksjonssystemer som foretrekker hendelseslevering.

Påkrevd scope

Webhook-administrasjon krever en API-nøkkel med:

webhooks:manage

Nye nøkler som opprettes i Settings, inkluderer dette scopet som standard.

Opprett endepunkt

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

Responsen inkluderer signing_secret bare én gang:

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

Lagre hele hemmeligheten på serveren din. Hvis du mister den, kall rotate-endepunktet og oppdater mottakeren.

URL-regler

Endepunkt-URL-er må bruke HTTPS. Rivya avviser URL-er med credentials, fragments, localhost-navn, lokale nettverksadresser, private IP-ranges, loopback-adresser og reserverte adresser.

Rivya sender alltid:

POST
Content-Type: application/json
ingen egendefinerte bruker-kontrollerte request headers
ingen automatisk redirect-following
en kort leveringstimeout

Hendelser

Nåværende hendelsestyper:

generation.succeeded
generation.failed

Webhook-payloads bruker samme offentlige generation serializer som statusendepunktet.

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

Leveringsheaders

Hver levering inkluderer:

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

Signaturinput:

${timestamp}.${rawBody}

Algoritme:

HMAC-SHA256 with the endpoint signing secret

Avvis forespørsler med foreldede tidsstempler. En toleranse på fem minutter er en praktisk standard.

JavaScript-verifisering

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

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)

Administrer endepunkter

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} deaktiverer endepunktet. Det sletter ikke leveringshistorikk.

Leveringsposter

List opp nylige hendelser:

GET /api/v1/webhook-events

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

List opp leveringsforsøk for et endepunkt:

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

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

Leveringsposter inkluderer status, HTTP-status, forsøkstall, request id, varighet, avkortet responsutdrag og offentlige feilfelt.

Testhendelse

Send en trygg testpayload:

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

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

Testhendelsen bruker webhook.test. Den oppretter ikke en genereringsoppgave, bruker ikke credits og inkluderer ikke en ekte resultat-URL.

Retry-policy

Rivya behandler HTTP 2xx som suksess.

Feil inkluderer nettverksfeil, timeout, redirect-responser og ikke-2xx-responser. Rivya prøver opptil fem forsøk:

umiddelbart
etter 1 minutt
etter 5 minutter
etter 30 minutter
etter 2 timer

Etter siste forsøk merkes hendelsen som failed.

Webhook-leveringsfeil endrer ikke genereringsstatus, credits, refusjoner eller oppgavehistorikk.

Sikkerhetssjekkliste

Verifiser HMAC-signaturen før du parser forretningslogikk.
Avvis foreldede tidsstempler.
Behandle testhendelser separat fra genereringshendelser.
Ikke logg fullstendige signeringshemmeligheter.
Returner 2xx bare etter at mottakeren din har akseptert hendelsen.
Behold polling som fallback for avstemming.

API-webhooks