Webhooks

非同期処理が完了した際にリアルタイムの通知を受け取ります。

セットアップ

StoryHubフィード管理画面で Webhook URL を設定してください。イベント発生時に、API がこの URL へ HTTP POST リクエストを送信します。

プッシュ候補の Webhooks

プッシュ候補ジョブが完了した場合（成功・エラーを問わず）、Webhook が送信されます：

{
  "event": "push_candidates.completed",
  "job_id": "job-uuid",
  "status": "completed",
  "download_url": "https://storage.googleapis.com/...",
  "completed_at": "2025-01-15T10:05:00Z"
}

失敗時：

{
  "event": "push_candidates.failed",
  "job_id": "job-uuid",
  "status": "failed",
  "error": "Description of the error",
  "failed_at": "2025-01-15T10:05:00Z"
}

署名の検証

すべての Webhook リクエストには、HMAC-SHA256 署名を含む X-StoryHub-Signature ヘッダーが付与されます。Webhook が正規のものであることを確認するために、署名を検証してください：

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

const crypto = require("crypto");

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

配信

プロパティ	値
HTTP メソッド	POST
Content-Type	application/json
タイムアウト	10 秒
リトライ	バックオフ付きで 3 回

エンドポイントが 2xx 以外のステータスコードを返した場合、Webhook はリトライされます。3 回失敗すると、配信は中止されます。

ベストプラクティス

• 必ず X-StoryHub-Signature ヘッダーを検証してください。
• 200 OK を速やかに返し、Webhook ペイロードの処理は非同期で行ってください。
• 冪等性を実装してください — Webhook は複数回配信される可能性があります。