Maak ondertekende Rivya API-webhookendpoints aan, verifieer deliverysignatures, inspecteer deliverypogingen en verstuur veilige testevents.

Gebruik API-webhooks wanneer je integratie wil dat Rivya je server informeert nadat een Public API-generatie een eindstatus bereikt.

Polling via GET /api/v1/generations/{taskId} blijft ondersteund. Webhooks voegen ondertekende callbacks toe voor productiesystemen die eventdelivery verkiezen.

Vereiste scope

Webhookbeheer vereist een API-sleutel met:

webhooks:manage

Nieuwe sleutels die in Settings worden aangemaakt, bevatten deze scope standaard.

Endpoint aanmaken

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

De response bevat signing_secret slechts een keer:

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

Bewaar het volledige secret op je server. Als je het kwijtraakt, roep je het rotate endpoint aan en werk je je receiver bij.

URL-regels

Endpoint-URL's moeten HTTPS gebruiken. Rivya weigert URL's met credentials, fragments, localhost-namen, lokale netwerkadressen, private IP-ranges, loopbackadressen en gereserveerde adressen.

Rivya verstuurt altijd:

POST
Content-Type: application/json
geen aangepaste requestheaders die door gebruikers worden beheerd
geen automatisch volgen van redirects
een korte delivery timeout

Events

Huidige eventtypes:

generation.succeeded
generation.failed

Webhookpayloads gebruiken dezelfde publieke generation serializer als het statusendpoint.

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

Deliveryheaders

Elke delivery bevat:

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

Invoer voor handtekening:

${timestamp}.${rawBody}

Algoritme:

HMAC-SHA256 with the endpoint signing secret

Weiger requests met verouderde timestamps. Een tolerantie van vijf minuten is een praktische standaard.

JavaScript-verificatie

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

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)

Endpoints beheren

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} schakelt het endpoint uit. Het verwijdert geen deliverygeschiedenis.

Deliveryrecords

Recente events tonen:

GET /api/v1/webhook-events

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

Deliverypogingen voor een endpoint tonen:

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

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

Deliveryrecords bevatten status, HTTP-status, attemptnummer, request id, duration, een ingekorte response snippet en publieke foutvelden.

Testevent

Verstuur een veilige testpayload:

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

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

Het testevent gebruikt webhook.test. Het maakt geen generatietaak aan, verbruikt geen credits en bevat geen echte result URL.

Retrybeleid

Rivya behandelt HTTP 2xx als succes.

Failures omvatten netwerkfouten, timeout, redirectresponses en non-2xx responses. Rivya probeert maximaal vijf keer:

onmiddellijk
na 1 minuut
na 5 minuten
na 30 minuten
na 2 uur

Na de laatste poging wordt het event gemarkeerd als failed.

Webhookdelivery-failures wijzigen de generatiestatus, credits, refunds of taakgeschiedenis niet.

Security checklist

Verifieer de HMAC-signature voordat je business logic verwerkt.
Weiger verouderde timestamps.
Behandel testevents apart van generatie-events.
Log geen volledige signing secrets.
Retourneer 2xx pas nadat je receiver het event heeft geaccepteerd.
Houd polling als fallback voor reconciliatie.

API-webhooks