Cipta endpoint webhook API Rivya bertandatangan, sahkan tandatangan delivery, periksa percubaan delivery dan hantar acara ujian yang selamat.

Gunakan webhook API apabila integrasi anda memerlukan Rivya memberitahu pelayan anda selepas penjanaan Public API mencapai keadaan terminal.

Polling GET /api/v1/generations/{taskId} masih disokong. Webhook menambah callback bertandatangan untuk sistem produksi yang memilih delivery berasaskan acara.

Scope Diperlukan

Pengurusan webhook memerlukan API key dengan:

webhooks:manage

Key baharu yang dicipta dalam Settings menyertakan scope ini secara lalai.

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

Respons menyertakan signing_secret sekali sahaja:

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

Simpan secret penuh pada pelayan anda. Jika anda kehilangannya, panggil endpoint rotate dan kemas kini penerima anda.

Peraturan URL

URL endpoint mesti menggunakan HTTPS. Rivya menolak URL dengan kelayakan, fragment, nama localhost, alamat rangkaian setempat, julat IP peribadi, alamat loopback dan alamat reserved.

Rivya sentiasa menghantar:

POST
Content-Type: application/json
tiada header permintaan tersuai yang dikawal pengguna
tiada tindakan mengikuti redirect secara automatik
timeout delivery yang pendek

Acara

Jenis acara semasa:

generation.succeeded
generation.failed

Payload webhook menggunakan public generation serializer yang sama seperti endpoint 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
    }
  }
}

Header Delivery

Setiap delivery menyertakan:

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

${timestamp}.${rawBody}

Algoritma:

HMAC-SHA256 with the endpoint signing secret

Tolak permintaan dengan timestamp lapuk. Toleransi lima minit ialah lalai yang praktikal.

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

Pengesahan 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)

Urus Endpoint

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} menyahdayakan endpoint. Ia tidak memadam sejarah delivery.

Rekod Delivery

Senaraikan acara terkini:

GET /api/v1/webhook-events

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

Senaraikan percubaan delivery untuk endpoint:

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

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

Rekod delivery merangkumi status, status HTTP, nombor percubaan, request id, tempoh, snippet respons dipendekkan dan medan ralat awam.

Acara Ujian

Hantar payload ujian yang selamat:

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

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

Acara ujian menggunakan webhook.test. Ia tidak mencipta tugasan penjanaan, tidak menggunakan kredit dan tidak menyertakan URL hasil sebenar.

Dasar Cuba Semula

Rivya menganggap HTTP 2xx sebagai berjaya.

Kegagalan merangkumi ralat rangkaian, timeout, respons redirect dan respons bukan 2xx. Rivya mencuba semula hingga lima percubaan:

serta-merta
selepas 1 minit
selepas 5 minit
selepas 30 minit
selepas 2 jam

Selepas percubaan terakhir, acara ditandakan failed.

Kegagalan delivery webhook tidak mengubah status penjanaan, kredit, bayaran balik atau sejarah tugasan.

Senarai Semak Keselamatan

Sahkan tandatangan HMAC sebelum menghurai logik perniagaan.
Tolak timestamp lapuk.
Kendalikan acara ujian secara berasingan daripada acara penjanaan.
Jangan log signing secret penuh.
Kembalikan 2xx hanya selepas penerima anda menerima acara.
Kekalkan polling sebagai fallback untuk penyelarasan.

Webhook API