API Webhooks ガイド
Rivya API の生成イベント通知を設定し、HMAC 署名の検証、配信記録の確認、テストイベント送信、再試行への対応を行います。
2026年11月5日 最終レビュー
API Webhook は Public API の生成タスクについて、署名付き通知をサーバーへ送ります。エンドポイントを登録してイベントを選び、配信ごとに検証してから処理します。
GET /api/v1/generations/{taskId} による確認も可能です。通知の欠落や遅延に備えてポーリングを残してください。
必要なスコープ
Webhook 管理には有効かつ期限内の Bearer API キーと次のスコープが必要です。
webhooks:manage設定で作る新しいキーには既定で含まれます。エンドポイント・イベント・配信記録はアカウントに属するため、同じスコープを持つ別のキーでも同じアカウントの記録を管理できます。
管理ルートには Public API と Webhook の両方の有効化が必要です。無効なら 503 public_api_disabled を返します。
Endpoint を作成する
POST /api/v1/webhookscurl 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"]
}'例のキーと URL を置き換えてください。登録のみで配信テストは行いません。
name は必須で前後の空白除去後 1〜120 文字。url も必須で下記の規則に従います。event_types は省略すると両生成イベントを購読し、指定時は対応する最大 2 種類の空でない配列を使います。
成功時は HTTP 201 です。次の ID・シークレット・日時は例です。完全な signing_secret は作成とシークレットのローテーション時だけ返り、一覧・取得・更新・無効化では返りません。
{
"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
}完全なシークレットをサーバーで安全に保存します。紛失時はローテーションし受信側を更新してください。以後の配信では新しいシークレットを使い、旧シークレットの猶予期間はありません。
作成やローテーションの応答が不明でも操作済みの場合があります。再作成前に一覧を確認します。既存の完全なシークレットは再取得できないため、応答を回収できなければローテーションします。
URL ルール
公開到達可能な HTTPS URL を使います。最大 2,048 文字で、認証情報やフラグメントを含めず、ループバック・プライベート・予約済みアドレスは使いません。
localhost 名、.localhost・.local で終わる名前、禁止対象の IPv4 リテラルを拒否します。登録時にホスト名の宛先を DNS 解決して確認することはありません。
配信は POST、Content-Type: application/json、Rivya の配信ヘッダーを使います。所有者指定のヘッダーやリダイレクトの自動追跡はなく、タイムアウトは 10 秒です。
イベント
対応イベントは次のとおりです。
generation.succeeded:タスクが成功し、settlement_statusがSETTLED。generation.failed:タスクが失敗。クレジット結果はsettlement_statusとfinal_creditsで確認し、このイベントだけで返金を判断しません。
Public API の生成タスクのみが対象で、Studio タスクや Chat 応答は対象外です。アカウントに有効なエンドポイントがある場合にキューへ登録し、有効かつ該当イベントを購読する宛先へ配信します。
本文は状態エンドポイントの公開生成フィールドのスナップショットです。成功しても精算照合待ちなら成功イベントはまだ発生しません。次の例は精算済みで、ID・日時・URL・クレジット額は例であり現在のモデル料金ではありません。api_version は本文の版です。
{
"id": "evt_...",
"type": "generation.succeeded",
"api_version": "2026-05-11",
"created_at": "2026-05-11T00:01:00.000Z",
"data": {
"generation": {
"id": "task_public_id",
"status": "succeeded",
"model": "z-image",
"reserved_credits": 1,
"final_credits": 1,
"settlement_status": "SETTLED",
"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 ヘッダー
配信には以下のヘッダーが付きます。タイムスタンプは Unix 秒で、値は例です。
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_...署名入力:
${timestamp}.${rawBody}アルゴリズム:
エンドポイント署名シークレットを使用した HMAC-SHA256受信したタイムスタンプをそのまま使い、ピリオドと未変更の本文を連結します。UTF-8 テキストとして読み、検証後に JSON 解析します。JSON.stringify による再構築・整形・文字正規化を行わないでください。
ローカル時刻より過去・未来へ 5 分を超えた値を拒否します。例は許容幅 300 秒と定時間のダイジェスト比較を使います。ヘッダー名は小文字、値は文字列で渡します。
JavaScript 検証
import crypto from "node:crypto";
function verifyRivyaWebhook({ rawBody, headers, signingSecret }) {
const timestamp = headers["rivya-webhook-timestamp"] || "";
const signature = headers["rivya-webhook-signature"] || "";
if (!/^[0-9]+$/.test(timestamp)) return false;
const timestampSeconds = Number(timestamp);
if (!Number.isSafeInteger(timestampSeconds)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - timestampSeconds) > 300) {
return false;
}
const actual = signature
.split(",")
.map((part) => part.trim())
.find((part) => part.startsWith("v1="))
?.slice(3);
if (!actual || !/^[a-f0-9]{64}$/i.test(actual)) return false;
const expected = crypto
.createHmac("sha256", signingSecret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(actual, "hex"),
Buffer.from(expected, "hex")
);
}Python 検証
import hashlib
import hmac
import re
import time
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", "")
if not re.fullmatch(r"[0-9]+", timestamp):
return False
try:
timestamp_seconds = int(timestamp)
except ValueError:
return False
if abs(int(time.time()) - timestamp_seconds) > 300:
return False
parts = (part.strip() for part in signature.split(","))
actual = next((part[3:] for part in parts if part.startswith("v1=")), "")
if not re.fullmatch(r"[a-fA-F0-9]{64}", actual):
return False
expected = hmac.new(
signing_secret.encode("utf-8"),
f"{timestamp}.{raw_body}".encode("utf-8"),
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(actual.lower(), expected)検証後に本文を解析し、業務処理の前にイベント id で重複を検出します。再試行は同じイベント ID と新しい日時・署名・リクエスト ID を使います。時刻検査だけでは重複防止になりません。
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-secretcurl 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_..."PATCH は name、url、event_types、status のうち少なくとも 1 つを更新します。状態は active または disabled。URL とイベントの規則は同じです。DELETE /api/v1/webhooks/{endpointId} は無効化し、履歴は削除しません。
キー欠落・無効・停止・期限切れや API 利用不可アカウントは 401、スコープ不足は 403、未知または他アカウントのエンドポイントは 404、入力・URL 不正は 400 です。API エラーと制限を参照してください。
Delivery 記録
アカウントの最近の生成イベント:
GET /api/v1/webhook-eventscurl https://rivya.ai/api/v1/webhook-events \
-H "Authorization: Bearer rvya_sk_..."エンドポイントの配信試行:
GET /api/v1/webhooks/{endpointId}/deliveriescurl https://rivya.ai/api/v1/webhooks/whend_.../deliveries \
-H "Authorization: Bearer rvya_sk_..."どちらも新しい順で既定 20 件、正の limit は最大 100、カーソルはありません。イベントは status、attempts_count、配信・再試行日時を含みます。配信記録は status、http_status、attempt_number、request_id、duration_ms、切り詰めた response_snippet、error_code、error_message を含みます。
テストイベント
有効なエンドポイントの登録 URL に 1 回テスト配信します。
POST /api/v1/webhooks/{endpointId}/testcurl -X POST https://rivya.ai/api/v1/webhooks/whend_.../test \
-H "Authorization: Bearer rvya_sk_..."webhook.test は data.ping: true とエンドポイント ID を含み、生成タスクや実結果 URL は含まず、生成クレジットを消費しません。実際の署名付き HTTP 配信を試みるため、生成イベントと分けて処理してください。
完了した管理呼び出しは HTTP 200 と配信結果を返します。status の success、failed、timeout、skipped を確認します。管理 API の 200 は受信側の受理を意味しません。
結果は直接返し、イベント・配信一覧に記録しません。成功・失敗統計は更新し、自動再試行のキューには入れません。
リトライポリシー
HTTP 2xx を受け取り、応答スニペットの読み取りまで完了すると成功です。ネットワーク・読み取りエラー、タイムアウト、リダイレクト、他の状態では失敗する場合があります。
生成イベントは最大 5 ラウンドで、成功記録のある宛先は次回以降スキップします。次回が実行可能になるまでの時間は前回終了から数えます。
第 1 回:キュー登録時。
第 2 回:1 分後。
第 3 回:5 分後。
第 4 回:30 分後。
第 5 回:2 時間後。
配信時刻の保証ではなく再試行の待ち時間です。バックグラウンド配信処理が必要で、遅延や停止によりさらに遅くなります。
現在有効で購読中の全宛先に成功記録があれば delivered、回数上限または有効な購読先なしなら failed です。失敗イベントでも一部の宛先は受理済みの場合があります。配信失敗は生成状態・クレジット・返金・タスク履歴を変更しません。
セキュリティチェックリスト
処理前に HMAC を検証します。
古い時刻を拒否し、イベント ID の重複を検出します。
テストと生成イベントを分けます。
完全な署名シークレットを記録しません。
受理後にだけ
2xxを返します。照合用にポーリングを残します。
