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.

Polling med GET /api/v1/generations/{taskId} stöds fortfarande. Webhooks lägger till signerade callbacks för produktionssystem som föredrar händelseleverans.

Nödvändig scope

Webhookhantering kräver en API-nyckel med:

webhooks:manage

Nya nycklar som skapas i Settings innehåller denna scope som standard.

Skapa endpoint

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

Endpoint-URL:er måste vara HTTPS. Rivya avvisar URL:er med credentials, fragment, localhost-namn, lokala nätverksadresser, privata IP-intervall, loopback-adresser 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 with the endpoint signing secret

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 endpoint:

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

Webhookleveransfel ändrar inte genereringsstatus, credits, återbetalningar 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 polling som fallback för avstämning.

API-webhooks