Opret signerede Rivya API webhook-endpoints, verificer delivery-signaturer, inspicer delivery-forsøg, og send sikre test-events.

Brug API webhooks, når din integration har brug for, at Rivya giver din server besked, efter en Public API-generation når en terminal tilstand.

Polling af GET /api/v1/generations/{taskId} understøttes stadig. Webhooks tilføjer signerede callbacks til production-systemer, der foretrækker event delivery.

Påkrævet scope

Webhook-administration kræver en API-nøgle med:

webhooks:manage

Nye nøgler oprettet i Settings inkluderer dette scope som standard.

Opret 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 inkluderer kun signing_secret é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
}

Gem den fulde secret på din server. Hvis du mister den, skal du kalde rotate-endpointet og opdatere din receiver.

URL-regler

Endpoint-URL'er skal være HTTPS. Rivya afviser URL'er med credentials, fragments, localhost-navne, lokale netværksadresser, private IP-ranges, loopback-adresser og reserverede adresser.

Rivya sender altid:

POST
Content-Type: application/json
ingen brugerdefinerede request headers
ingen automatisk redirect-following
en kort delivery-timeout

Events

Aktuelle eventtyper:

generation.succeeded
generation.failed

Webhook-payloads bruger den samme offentlige generation serializer som statusendpointet.

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

Hver delivery 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

Afvis anmodninger med for gamle timestamps. En tolerance på fem minutter er et praktisk udgangspunkt.

JavaScript-verificering

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

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 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} deaktiverer endpointet. Det sletter ikke delivery-historik.

Delivery records

List seneste events:

GET /api/v1/webhook-events

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

List delivery-forsøg for et endpoint:

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

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

Delivery records inkluderer status, HTTP-status, forsøgsnummer, request id, varighed, afkortet response snippet og offentlige fejlfelter.

Test-event

Send en sikker testpayload:

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

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

Testeventet bruger webhook.test. Det opretter ikke en genereringsopgave, forbruger ikke credits og inkluderer ikke en rigtig resultat-URL.

Retry-politik

Rivya behandler HTTP 2xx som succes.

Fejl omfatter netværksfejl, timeout, redirect-svar og non-2xx-svar. Rivya retryer op til fem forsøg:

med det samme
efter 1 minut
efter 5 minutter
efter 30 minutter
efter 2 timer

Efter sidste forsøg markeres eventet som failed.

Webhook-delivery-fejl ændrer ikke generationsstatus, credits, refusioner eller task-historik.

Sikkerhedstjekliste

Verificer HMAC-signaturen, før du parser forretningslogik.
Afvis for gamle timestamps.
Behandl testevents separat fra generationsevents.
Log ikke fulde signing secrets.
Returnér kun 2xx, efter din receiver har accepteret eventet.
Behold polling som fallback til afstemning.

API Webhooks