↓
Rivya AI ドキュメント

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

例のキーと 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-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_..."

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-events
curl https://rivya.ai/api/v1/webhook-events \
  -H "Authorization: Bearer rvya_sk_..."

エンドポイントの配信試行:

GET /api/v1/webhooks/{endpointId}/deliveries
curl 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}/test
curl -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 を返します。

  • 照合用にポーリングを残します。

関連ページ