Skapa signerade Rivya API-webhookendpoints, verifiera leveranssignaturer, granska leveransförsök och skicka säkra testhändelser.

Använd API-webhooks när din integration behöver att Rivya meddelar din server efter att en Public API-generation når ett terminalt tillstånd.

Regelbunden statuskontroll med GET /api/v1/generations/{taskId} stöds fortfarande. Webhooks ger produktionssystem signerade aviseringar när de föredrar att ta emot händelser.

Nödvändig behörighet

Webhookhantering kräver en API-nyckel med:

webhooks:manage

Nya nycklar som skapas i Inställningar innehåller denna behörighet som standard.

Skapa en mottagare

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

Svaret innehåller signing_secret bara en gång:

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

Spara hela hemligheten på din server. Om du tappar bort den, anropa rotate-endpointen och uppdatera din mottagare.

URL-regler

Mottagarens URL måste använda HTTPS. Rivya avvisar URL:er med autentiseringsuppgifter, fragment, localhost-namn, lokala nätverksadresser, privata IP-intervall, återkopplingsadresser och reserverade adresser.

Rivya skickar alltid:

POST
Content-Type: application/json
inga användarstyrda anpassade request headers
ingen automatisk redirect-följning
en kort leveranstimeout

Händelser

Aktuella händelsetyper:

generation.succeeded
generation.failed

Webhookpayloads använder samma offentliga generation-serializer som statusendpointen.

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

Leveransheaders

Varje leverans innehåller:

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}

Algoritm:

HMAC-SHA256 med mottagarens signeringshemlighet

Avvisa begäranden med gamla tidsstämplar. Fem minuters tolerans är en praktisk standard.

JavaScript-verifiering

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

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)

Hantera endpoints

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} inaktiverar endpointen. Den tar inte bort leveranshistorik.

Leveransposter

Lista senaste händelser:

GET /api/v1/webhook-events

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

Lista leveransförsök för en mottagare:

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

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

Leveransposter innehåller status, HTTP-status, försöknummer, request id, längd, trunkerat response snippet och offentliga felfält.

Testhändelse

Skicka en säker testpayload:

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

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

Testhändelsen använder webhook.test. Den skapar ingen genereringsuppgift, förbrukar inga krediter och innehåller ingen riktig resultat-URL.

Retrypolicy

Rivya behandlar HTTP 2xx som framgång.

Fel omfattar nätverksfel, timeout, redirect-svar och icke-2xx-svar. Rivya försöker upp till fem gånger:

omedelbart
efter 1 minut
efter 5 minuter
efter 30 minuter
efter 2 timmar

Efter sista försöket markeras händelsen som failed.

Fel vid webhookleverans ändrar inte genereringsstatus, krediter, återföringar eller uppgiftshistorik.

Säkerhetschecklista

Verifiera HMAC-signaturen innan du parsar affärslogik.
Avvisa gamla tidsstämplar.
Behandla testhändelser separat från genereringshändelser.
Logga inte fullständiga signing secrets.
Returnera 2xx först efter att din mottagare har accepterat händelsen.
Behåll regelbunden statuskontroll som reserv för avstämning.

API-webhooks