Luo allekirjoitettuja Rivya API -webhook-endpointteja, vahvista toimitusten allekirjoitukset, tarkista toimitusyritykset ja lähetä turvallisia testitapahtumia.

Käytä API-webhookeja, kun integraatiosi tarvitsee Rivyan ilmoittavan palvelimellesi sen jälkeen, kun Public API -generointi saavuttaa päätetilan.

Pollaus endpointilla GET /api/v1/generations/{taskId} on edelleen tuettu. Webhookit lisäävät allekirjoitetut callbackit tuotantojärjestelmille, jotka suosivat tapahtumatoimitusta.

Vaadittu scope

Webhookien hallinta vaatii API-avaimen, jossa on:

webhooks:manage

Asetuksissa luodut uudet avaimet sisältävät tämän scope-oikeuden oletuksena.

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

Vastaus sisältää signing_secret-arvon vain kerran:

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

Tallenna koko salaisuus palvelimellesi. Jos kadotat sen, kutsu kierrätysendpointtia ja päivitä vastaanottimesi.

Endpoint-URL-osoitteiden täytyy olla HTTPS-osoitteita. Rivya hylkää URL-osoitteet, joissa on tunnuksia, fragmentteja, localhost-nimiä, paikallisverkon osoitteita, yksityisiä IP-alueita, loopback-osoitteita tai varattuja osoitteita.

Rivya lähettää aina:

POST
Content-Type: application/json
ei käyttäjän hallitsemia mukautettuja request-headereita
ei automaattista redirectien seuraamista
lyhyen toimitusaikakatkaisun

Tapahtumat

Nykyiset tapahtumatyypit:

generation.succeeded
generation.failed

Webhook-payloadit käyttävät samaa julkista generointiserialisoijaa kuin status-endpoint.

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

Toimitusheaderit

Jokainen toimitus sisältää:

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

Allekirjoituksen syöte:

${timestamp}.${rawBody}

Algoritmi:

HMAC-SHA256 with the endpoint signing secret

Hylkää pyynnöt, joissa on vanhentunut timestamp. Viiden minuutin toleranssi on käytännöllinen oletus.

JavaScript-vahvistus

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

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)

Hallitse endpointeja

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} poistaa endpointin käytöstä. Se ei poista toimitushistoriaa.

Toimitustietueet

Listaa viimeaikaiset tapahtumat:

GET /api/v1/webhook-events

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

Listaa endpointin toimitusyritykset:

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

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

Toimitustietueet sisältävät tilan, HTTP-statuksen, yritysnumeron, request id:n, keston, katkaistun vastauskatkelman ja julkiset virhekentät.

Testitapahtuma

Lähetä turvallinen testipayload:

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

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

Testitapahtuma käyttää tyyppiä webhook.test. Se ei luo generointitehtävää, ei kuluta krediittejä eikä sisällä oikeaa tulos-URL-osoitetta.

Retry-käytäntö

Rivya käsittelee HTTP 2xx -vastaukset onnistumisena.

Epäonnistumisia ovat verkkovirheet, aikakatkaisu, redirect-vastaukset ja muut kuin 2xx-vastaukset. Rivya yrittää uudelleen enintään viisi kertaa:

heti
1 minuutin kuluttua
5 minuutin kuluttua
30 minuutin kuluttua
2 tunnin kuluttua

Viimeisen yrityksen jälkeen tapahtuma merkitään failed.

Webhook-toimitusten epäonnistumiset eivät muuta generoinnin tilaa, krediittejä, hyvityksiä tai tehtävähistoriaa.

Turvallisuuden tarkistuslista

Vahvista HMAC-allekirjoitus ennen liiketoimintalogiikan jäsentämistä.
Hylkää vanhentuneet timestampit.
Käsittele testitapahtumat erillään generointitapahtumista.
Älä lokita kokonaisia signing secret -arvoja.
Palauta 2xx vasta sen jälkeen, kun vastaanottimesi on hyväksynyt tapahtuman.
Pidä pollaus varalla täsmäytystä varten.

API-webhookit