Webhook
コールバック形式、HMAC 署名、リプレイ防止、再配信。
createTask の callBackUrl を指定すると、タスクが終端状態になったときに一度通知をキューへ追加します。queued から running への途中通知はありません。 v2 の再送は同じ request_id と業務データを保持し、url と expiresAt のみ更新します。受信した生の本文で署名を検証し、request_id で重複排除してください。
signature = base64(
HMAC-SHA256(
secret,
"<task_id>.<timestamp>.<sha256_hex(raw_body)>"
)
)署名を検証する
X-Webhook-Signature は HMAC-SHA256 の Base64 です。署名対象は <task_id>.<timestamp>.<sha256_hex(raw_body)> で、task_id は data.taskId から取得します。JSON を再シリアライズせず、受信した raw body をそのままハッシュしてください。
X-Webhook-Timestamp が許容時間外なら、署名が正しくても拒否します。比較は一定時間で行い、アカウントに空でない webhook secret を設定してください。
重複配信に備える
request_id は配信 ID であり、再送でも変わりません。自社データベースで一意制約を設定し、既に処理済みなら 2xx を返します。先に受理して内部キューへ入れ、重い処理は応答後に実行してください。
body の code は failed タスクでも 200 です。成功判定には必ず data.state を使います。
完全なフィールド定義は OpenAPI 3.1 仕様を参照してください。