Webhook

POST https://api.beatapi.io/v1/webhooks

BeatAPI タスクの完了通知を必要に応じて受け取るための、Webhook エンドポイントを作成します。

認証

Authorization   string   必須

BeatAPI の API キーを Bearer トークンとして送信します。API キーはダッシュボードで作成できます。

Authorization: Bearer <BEATAPI_API_KEY>

通常の API キーは、信頼できるサーバーで管理してください。リクエストボディには Content-Type: application/json が必要です。対応するエンドポイントでは Idempotency-Key は任意ですが、同一のリクエストボディで安全に再試行するために指定を推奨します。

リクエストボディ

url   string   必須

BeatAPI のタスクイベントを受信する、公開 HTTPS コールバック URL です。localhost やプライベートネットワークの URL は使用しないでください。

形式: uri

description   string   任意

アカウント内でエンドポイントを識別するための、任意の内部ラベルです。

events   string[]   任意

通知するタスクイベントです。省略すると、task.succeeded と task.failed の両方を購読します。

レスポンス

リクエストが成功すると、HTTP 201 が返されます。

{
  "data": {
    "id": "wh_9aBcD",
    "object": "webhook_endpoint",
    "url": "https://example.com/beatapi-webhook",
    "description": "Production webhook",
    "events": [
      "task.succeeded",
      "task.failed"
    ],
    "status": "active",
    "secret": "whsec_example_store_this_once",
    "created_at": 1782210000,
    "updated_at": 1782210000
  }
}

コールバックの署名を検証する

BeatAPI は通知のたびに x-beatapi-event、x-beatapi-timestamp、x-beatapi-signature を送信します。次のデータから HMAC-SHA256 を計算し、16 進数の署名値を求めてください。

timestamp + "." + raw_request_body

この作成リクエストで返されたエンドポイントの secret を使います。署名は定数時間で比較し、JSON を解析する前に元のバイト列をそのまま検証してください。リプレイ攻撃を抑えるため、5 分より古いタイムスタンプは拒否してください。

エンドポイントを管理する

• GET /v1/webhooks：Webhook エンドポイントの一覧を取得します。
• GET /v1/webhooks/{id}：Webhook エンドポイントの情報を取得します。
• PATCH /v1/webhooks/{id}：Webhook エンドポイントを更新します。
• DELETE /v1/webhooks/{id}：Webhook エンドポイントを削除します。

次の手順

コールバックのペイロードを解析する前に、毎回署名を検証してください。通知が遅延・失敗した場合も、GET /v1/tasks/{task_id} のポーリング結果をタスク状態の正しい情報として扱います。

エラー