Webhooks

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

セットアップ

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

プッシュ候補の Webhooks

プッシュ候補ジョブが完了した場合（成功・エラーを問わず）、Webhook が送信されます。event はそれぞれ push_job.completed / push_job.failed です。

成功時:

{
  "event": "push_job.completed",
  "job_id": "01HZX9...",
  "tenant_id": "...",
  "scenario_id": "...",
  "status": "completed",
  "target_user_count": 1234,
  "failed_user_count": 3,
  "candidates_generated": 3702,
  "consumed_credits": 12.34,
  "download_url": "https://...",
  "download_url_expires_at": "2025-01-15T11:05:00Z",
  "filter_stats": {
    "total_audience": 5000,
    "excluded_due_to_null_last_active": 200,
    "excluded_due_to_last_active_days": 3500,
    "excluded_due_to_registered_range": 66
  },
  "error": null,
  "completed_at": "2025-01-15T10:05:00Z"
}

失敗時:

{
  "event": "push_job.failed",
  "job_id": "01HZX9...",
  "tenant_id": "...",
  "scenario_id": "...",
  "status": "failed",
  "target_user_count": null,
  "failed_user_count": null,
  "candidates_generated": null,
  "consumed_credits": 0,
  "download_url": null,
  "download_url_expires_at": null,
  "filter_stats": null,
  "error": "Description of the error",
  "completed_at": "2025-01-15T10:05:00Z"
}

各フィールドの意味は プッシュ候補 と同じです。target_mode=condition で対象 0 人になった場合も push_job.completed として通知されます（consumed_credits=0、空の JSONL が発行されます）。

署名の検証

すべての 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 は複数回配信される可能性があります。