NB

Webhook

タスクの完了や失敗時にリアルタイムで通知を受け取ります

概要

Webhookを使用すると、画像や動画生成タスクが完了した際にHTTPコールバックを受け取ることができます。結果をポーリングで確認する代わりに、Webhookエンドポイントを設定して自動通知を受け取ることができます。

利用可能なイベント

task.completedタスクが正常に完了したときにトリガーされます
task.failedタスクが失敗したときにトリガーされます
GET/api/v1/webhooks
すべてのWebhook設定を一覧表示します

返信

{
  "success": true,
  "data": [
    {
      "id": 1,
      "url": "https://your-server.com/webhook",
      "events": ["job.completed", "job.failed"],
      "status": "active"
    }
  ]
}
POST/api/v1/webhooks
新しいWebhookエンドポイントを作成する

リクエストボディ

{
  "url": "https://your-server.com/webhook",
  "events": ["job.completed", "job.failed"],
  "secret_key": "your-secret-key"
}

本文フィールド

パラメータタイプ必須説明
urlstring必須WebhookエンドポイントURL
eventsstring[]必須購読するイベント
secret_keystringオプション署名検証用シークレット

返信

{
  "success": true,
  "data": {
    "id": 1,
    "url": "https://your-server.com/webhook",
    "events": ["job.completed", "job.failed"],
    "status": "active"
  }
}
DELETE/api/v1/webhooks/{id}
ウェブフックエンドポイントを削除

返信

{
  "success": true,
  "data": { "id": 1 }
}
Webhookペイロード
イベントが発生すると、以下のペイロードを含むPOSTリクエストをあなたのWebhook URLに送信します：

ヘッダー

ヘッダー説明
X-Webhook-TimestampリクエストのUnixタイムスタンプ
X-Webhook-SignatureHMAC-SHA256 検証用署名

サンプルペイロード

{
  "event": "job.completed",
  "task_id": "task_xxx",
  "task_type": "image",
  "status": "completed",
  "data": {
    "url": "https://cdn.example.com/image.png",
    "credits_charged": 6
  },
  "timestamp": "2024-12-23T10:00:00Z"
}
署名検証
HMAC-SHA256を使用してWebhookの真正性を検証する
const crypto = require('crypto');

function verifySignature(payload, signature, secret, timestamp) {
  const message = `${timestamp}.${JSON.stringify(payload)}`;
  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return `v1=${expectedSig}` === signature;
}
Nano Banana Pro API