Skip to main content
Webhook は、イベント発生と同時にあなたの HTTPS エンドポイントへイベントを送信します。ポーリングは不要です。登録と管理は Webhook API で行います。
アウトバウンド Webhook は open_api_advanced ライセンスと、webhooks:manage スコープを持つキーが必要です。

イベント

ペイロードの形

各配信は次のエンベロープを持つ POST です:

署名を検証する

各配信には X-Comdesk-Signature ヘッダー(生のリクエストボディの HMAC-SHA256、Webhook に紐づく API キーを鍵とする)が付きます。偽造リクエストを拒否するため、処理前に必ず検証してください。
HMAC は、JSON のパースや再シリアライズ前の生のリクエストボディのバイト列に対して計算してください。JSON を再エンコードするとバイト列が変わり、検証が失敗します。比較は定数時間で行ってください。

リプレイ対策

署名は真正性を証明しますが、新しさは証明しません。次も併せて強制してください:
  1. 処理した各イベントの event_id を保存し、24 時間以内の重複を拒否します(再送は同じ event_id を再利用するため、ハンドラーの冪等性も担保されます)。
  2. timestamp が受信時刻から 5 分以上ずれているイベントを拒否します。

再送スケジュール

エンドポイントが 10 秒以内に応答しない、または 2xx 以外を返した場合、Comdesk は指数バックオフで最大 5 回再送します: イベントを受理したら(キューに永続化したら)すぐに 2xx を返し、その後に非同期で処理してください。すべての配信試行は管理画面の Webhook 配信ログに記録されます。