Webhook の使い方：動画が完成したらすぐに通知を受け取る

動画の生成には時間がかかります。5〜10 秒の動画なら通常は数分から 15 分ほど、30 秒の動画なら 20〜30 分かかり、混み合う時間帯には順番待ちになることもあります。これまでは数秒おきにタスクの状態を照会するしかなく、ループを書き、タイムアウトに対処し、サービスを再起動したときにはどのタスクがまだ終わっていないかを把握しておく必要がありました。

もうその必要はありません。タスクが終わった瞬間に、成功でも失敗でも、結果をお使いのサーバーへ直接送信します。

受け取り方は 2 通り

• アカウントの既定の送信先：コンソールで「設定 → Webhook」を開き、イベントを受け取る URL を入力して、必要なイベントにチェックを入れます。以降、API から送信した動画・画像のタスクは、終了するたびに結果が届きます。
• リクエストごとに指定：タスクを送信するときに callback_url を付けると、そのタスクの結果はその URL にだけ送信されます。callBackUrl と書き慣れている場合は、そのままでも使えます。

curl https://nezhagate.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5", "prompt": "雨の夜、通りを流れていく紙の船", "duration": 5,
       "callback_url": "https://your-app.com/webhooks/nezhagate"}'

使いどころ

• 動画アプリ、ミニプログラム、Web サイト：ユーザーは送信後すぐにページを閉じてかまいません。動画ができあがると通知が届くので、アプリ内メッセージ、SMS、メールでユーザーに知らせ、動画をその人のライブラリに追加します。
• 画像の一括生成：商品画像や広告素材を一度に何百枚も送信すると、1 枚できあがるごとにメディアライブラリや CDN に保存されていきます。失敗した分は別に記録されるので、プロンプトを調整して再送信できます。
• チャットボット：Telegram、Discord、Lark、WeCom のグループで誰かがプロンプトを投稿すると、ボットはすぐに「生成中…」と返信し、通知が届いたら動画をグループに投稿します。
• サーバーレス関数：Vercel、Cloudflare Workers、各種クラウド関数は、30 分も続くポーリングループには向いていません。関数は送信後すぐに終了してかまいません。次の処理は通知の到着をきっかけに動き出します。
• 残高不足の通知：残高が設定したクレジット数を下回ると、通知が 1 回届きます。チームの Slack、Lark、DingTalk のチャンネルに流しておけば、夜中にサービスが止まってから気づくのではなく、残高が尽きる前に誰かがチャージできます。

通知は信頼できますか？

• 検証できる：すべての通知に Standard Webhooks 方式の署名が付いています（OpenAI の Webhook も同じ方式です）。ほとんどの言語に既製のライブラリがあり、数行のコードで、通知が確かに当社から送られたものかを確認できます。
• 自動で再試行：サーバーが 10 秒以内に 2xx を返さない場合は、1 分後、5 分後、30 分後、2 時間後、6 時間後に再送信します。再試行してもイベント ID は変わらないので、重複は簡単に排除できます。
• 必要な情報がそろう：通知の内容はタスク照会エンドポイントが返すものとまったく同じで、動画の URL や使用量も含まれます。失敗したタスクはすでに全額返金済みで、失敗の理由も通知に記載されます。
• 記録が残る：コンソールには最近の送信履歴と各回の結果が表示され、30 日間保存されます。個別に再送信することもできます。

3 ステップで設定

1. POST リクエストを受け付ける URL をサーバーに用意します。Webhook ドキュメント に、Python と Node.js で署名を検証する完全なサンプルがあります。
2. コンソールで「設定 → Webhook」を開き、URL を入力して「テストイベントを送信」をクリックし、通知が届くことを確認します。
3. あとはいつもどおりタスクを送信し、通知を待つだけです。特定のタスクの結果だけを別の送信先に届けたい場合は、そのリクエストに callback_url を追加します。