Creeaza endpointuri webhook Rivya API semnate, verifica semnaturile livrarilor, inspecteaza incercarile de livrare si trimite evenimente de test sigure.

Foloseste webhookuri API cand integrarea ta are nevoie ca Rivya sa notifice serverul tau dupa ce o generare Public API ajunge intr-o stare terminala.

Pollingul GET /api/v1/generations/{taskId} ramane acceptat. Webhookurile adauga callbackuri semnate pentru sisteme de productie care prefera livrarea de evenimente.

Scope necesar

Gestionarea webhookurilor necesita o cheie API cu:

webhooks:manage

Cheile noi create in Settings includ implicit acest scope.

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

Raspunsul include signing_secret o singura data:

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

Stocheaza secretul complet pe serverul tau. Daca il pierzi, apeleaza endpointul de rotatie si actualizeaza serverul receptor.

Reguli URL

URL-urile endpointurilor trebuie sa fie HTTPS. Rivya respinge URL-uri cu credentiale, fragmente, nume localhost, adrese de retea locala, intervale IP private, adrese loopback si adrese rezervate.

Rivya trimite intotdeauna:

POST
Content-Type: application/json
fara headere de cerere personalizate controlate de utilizator
fara urmarire automata a redirecturilor
un timeout scurt de livrare

Evenimente

Tipuri curente de evenimente:

generation.succeeded
generation.failed

Payloadurile webhook folosesc acelasi serializer public de generare ca endpointul de status.

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

Headere de livrare

Fiecare livrare include:

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

Input pentru semnatura:

${timestamp}.${rawBody}

Algoritm:

HMAC-SHA256 cu secretul de semnare al endpointului

Respinge cererile cu timestampuri vechi. O toleranta de cinci minute este o valoare practica implicita.

Verificare JavaScript

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"));
}

Verificare Python

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)

Gestioneaza endpointuri

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} dezactiveaza endpointul. Nu sterge istoricul livrarilor.

Inregistrari de livrare

Listeaza evenimente recente:

GET /api/v1/webhook-events

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

Listeaza incercarile de livrare pentru un endpoint:

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

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

Inregistrarile de livrare includ status, status HTTP, numarul incercarii, ID-ul cererii, durata, fragment trunchiat de raspuns si campuri publice de eroare.

Eveniment de test

Trimite un payload de test sigur:

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

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

Evenimentul de test foloseste webhook.test. Nu creeaza o sarcina de generare, nu consuma credite si nu include un URL real de rezultat.

Politica de reincercare

Rivya trateaza HTTP 2xx ca succes.

Esecurile includ erori de retea, timeout, raspunsuri redirect si raspunsuri non-2xx. Rivya reincearca pana la cinci incercari:

imediat
dupa 1 minut
dupa 5 minute
dupa 30 de minute
dupa 2 ore

Dupa incercarea finala, evenimentul este marcat failed.

Esecurile de livrare webhook nu schimba statusul generarii, creditele, rambursarile sau istoricul sarcinii.

Checklist de securitate

Verifica semnatura HMAC inainte sa parsezi logica de business.
Respinge timestampurile vechi.
Trateaza evenimentele de test separat de evenimentele de generare.
Nu loga secretele complete de semnare.
Returneaza 2xx doar dupa ce serverul receptor a acceptat evenimentul.
Pastreaza pollingul ca optiune de rezerva pentru reconciliere.

API Webhooks