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