Webhook連携ガイド
イベントをエンドポイントに配信するためにWebhookを連携します。
Webhookの仕組み
Webhookは、HTTP POSTリクエストをエンドポイントに送信します。各リクエストには、次の特徴があります。
- 完全なイベントペイロードをJSONとして含みます。
- CloudEvents仕様 （新しいウィンドウで開きます）に従います。
- 検証に使用するIndeed署名が含まれます。
Webhookリクエスト形式
Webhookシステムは、CloudEvents仕様 （新しいウィンドウで開きます）を実装しています。
| リクエスト | 説明 |
|---|---|
| メソッド | HTTP POST |
| Content-Type | application/cloudevents+json |
| ヘッダー |
|
| ボディ | CloudEvents形式のイベントデータを含むJSONペイロードです。 |
| ボディ属性 |
|
HTTPレスポンスコードの処理
| カテゴリ | HTTPコード | Webhookシステムのアクション | パートナーのアクション |
|---|---|---|---|
| 成功 |
| 配信を完了としてマークします。再試行しません。 | イベントを処理する前にレスポンスを返します。 |
| リダイレクト |
| レスポンスをクライアントエラーとして扱います。 | エンドポイントの設定を修正します。 |
| クライアントエラー |
（ | 指数バックオフを使用して再試行します。 | エンドポイントの設定を確認してから、エンドポイントを修正します。 |
| レート制限エラー | 429 | レート制限ヘッダーを読み取り、指定された遅延後に再試行します。アラートは送信しません。 | 不要です。 |
| サーバーエラー |
| 指数バックオフを使用して再試行します。 |
|
再試行動作
Webhookシステムは、エンドポイントが受け入れるまで、失敗した配信を再試行します。
| 特性 | 値 |
|---|---|
| 最大再試行回数 | 実質的に無制限です。 |
| 初回再試行間隔 | 10ミリ秒 |
| バックオフ乗数 | 2.0 各試行後に間隔が2倍になります。 |
| 最大間隔 | 7,200秒（2時間） |
再試行があるため、イベントは複数回、かつ順不同で到着する場合があります。対応方法については、べき等なイベント処理のためにイベントIDを使用するをご覧ください。
連携手順
パートナー連携チェックリスト
特に記載がない限り、すべての手順が必須です。
- 1.有効なSSL証明書を持つHTTPSエンドポイントを設定する。
- 2.Webhook署名検証を実装する（任意）。
- 3.イベントを非同期で処理する。処理する前に
2xxでレスポンスを返します。 - 4.べき等なイベント処理のためにイベントIDを使用する。
- 5.WebhookルートのCSRF保護を無効にする。
- 6.適切なステータスコードでエラーを処理する。
- 7.必要に応じて、レート制限ヘッダーをサポートする。
- 8.配信の失敗を監視し、アラートを設定する。
1. 有効なSSL証明書を持つHTTPSエンドポイントを設定する
サーバー上に、POSTリクエストを受信するHTTPSエンドポイントを作成します。IndeedはTLS v1.2およびv1.3をサポートしています。
2. Webhook署名検証を実装する
Indeedがイベントを送信したことを確認するために、X-Indeed-Signatureヘッダーを検証します。
署名ヘッダーの形式は次のとおりです。
X-Indeed-Signature: <signature>3. イベントを非同期で処理する
- リクエストを受信したら、すぐに
2xxレスポンスを返します。 - イベントをキューに入れ、レスポンスを返した後に処理します。そうしないと、エンドポイントがタイムアウトする場合があります。
4. べき等なイベント処理のためにイベントIDを使用する
Webhookハンドラーは、べき等になるように設計します。Indeedは、再試行やネットワークの問題により、同じイベントを複数回配信する場合があります。
重複に対応するには、次のようにします。
- すでに処理したイベントを、イベントIDを使用して追跡します。
- イベントの順序に依存しないようにします。
5. WebhookルートのCSRF保護を無効にする
WebフレームワークでCSRFトークンを検証する場合は、Webhookルートをこの保護の対象外にします。
6. 適切なステータスコードでエラーを処理する
次のステータスコードを返します。
2xx：イベントを受信しました。429：Indeedに対してレート制限を適用しています。Retry-Afterヘッダーを含めます。5xx：サーバーで障害が発生したため、Indeedは再試行します。
7. レート制限ヘッダーをサポートする
| ヘッダー | 説明 |
|---|---|
Retry-After | Webhookシステムでは、次のヘッダー形式をサポートしています。
|
X-RateLimit | レート制限ウィンドウがリセットされるUNIXタイムスタンプです。 |
これらのヘッダーを送信せずにIndeedに対してレート制限を適用した場合は、次のようになります。
- デフォルト待機時間：3秒
- 以降の再試行：指数バックオフ
8. Webhook配信の失敗を監視し、アラートを設定する
Webhook配信を監視します。
- 受信したすべてのWebhookをログに記録します。
- 処理の成功または失敗のメトリクスを追跡します。
- 繰り返し発生する失敗に対してアラートを設定します。
関連項目
ガイド
- CloudEvents - Version 1.0.2 （新しいウィンドウで開きます） — イベントデータの形式を定義する、ベンダーに依存しない仕様です。
- 求人ライフサイクルイベントWebhookガイド — 求人ライフサイクルステータスイベントのイベントスキーマとデータスキーマです。
サポート
Webhook連携のサポートについては、Indeedの連携担当チームにお問い合わせください。