アウトバウンド Webhook は
open_api_advanced ライセンスと、webhooks:manage スコープを持つキーが必要です。イベント
ペイロードの形
各配信は次のエンベロープを持つPOST です:
署名を検証する
各配信にはX-Comdesk-Signature ヘッダー(生のリクエストボディの HMAC-SHA256、Webhook に紐づく API キーを鍵とする)が付きます。偽造リクエストを拒否するため、処理前に必ず検証してください。
リプレイ対策
署名は真正性を証明しますが、新しさは証明しません。次も併せて強制してください:- 処理した各イベントの
event_idを保存し、24 時間以内の重複を拒否します(再送は同じevent_idを再利用するため、ハンドラーの冪等性も担保されます)。 timestampが受信時刻から 5 分以上ずれているイベントを拒否します。
再送スケジュール
エンドポイントが 10 秒以内に応答しない、または 2xx 以外を返した場合、Comdesk は指数バックオフで最大 5 回再送します:
イベントを受理したら(キューに永続化したら)すぐに
2xx を返し、その後に非同期で処理してください。すべての配信試行は管理画面の Webhook 配信ログに記録されます。