Webhook の管理は /api/v2/webhooks で利用できます。Webhook URL と署名用の情報は秘密として扱ってください。
始める前に
ワークスペースで必要最小限のアクセスを持つ API キーを作成し、連携に必要なイベントの種類を決めます。
手順
- Settings → Integrations を開きます。
- Webhook の宛先を作成または選択します。
- 設定したイベント ID とエンドポイントの状態を記録します。
- 本番以外の受信先へテストリクエストを送ります。
- 本番処理を有効にする前に、レスポンスを確認して配信試行を調べます。
受信側を idempotent にします。payload を検証してからイベント ID を保存して確認応答を返します。アプリ内部のすべてのイベントが顧客向け Webhook とは限りません。
Webhook を設定して確認する
- イベント payload を受け取り、成功レスポンスを返す前にイベント ID を記録する endpoint を作成します。
- Settings → Integrations で、表示される Name、Target hook URL、Event type、必要に応じて Campaign または custom interest value を指定します。
- 保存して宛先を開き、Test を使います。受信側がイベントを記録し、API が
success: trueを返すことを確認します。 - Webhook events で
status_code、success、retry_count、will_retry、error_messageを確認します。 - URL が変わったら宛先を削除または更新します。削除しても過去の配信試行は消えません。
履歴には cursor pagination（limit と starting_after）を使います。再試行は at-least-once delivery として扱い、consumer を idempotent にします。
失敗からの復旧
受信側の 4xx は通常 payload または認証の修正が必要です。5xx または timeout は制限付き backoff で再試行できます。次の試行を Webhook events で確認し、event ID とマスクした状態を添えて報告します。
Webhook フィールド参照
| フィールド | 必須 | 意味 |
|---|---|---|
| Name | はい | 宛先のワークスペースラベル。 |
| Target hook URL | はい | 配信を受け付ける HTTPS endpoint。 |
| Event type | はい | event-types endpoint が返すイベント識別子。 |
| Campaign | 任意 | 選択時に1つのキャンペーンへイベントを限定する。 |
| Custom interest value | 条件付き | 選択したイベントが custom interest ラベルの場合に必須。 |
配信の確認
Test の後、受信側が event ID を保存し、成功レスポンスを返し、再試行時に重複レコードを作らないことを確認します。Webhook events で status_code、success、retry_count、will_retry、error_message、timestamp_next_retry を確認します。