Webhookガイド
Webhookと連携して、エンドポイントにイベントを配信します。
概要
IndeedのWebhookは、パートナーのエンドポイントにイベントを配信します。本ガイドでは、Webhookの仕組み、連携方法、ベストプラクティスを解説します。
Webhookのワークフロー
- 1.Webhookの仕組みを学ぶ。
- 2.Webhookシステムと連携する。
Webhookの仕組み
Webhookは、HTTP POSTリクエストでイベント通知をエンドポイントに送信します。各配信は次の特徴を持ちます。
- JSON形式のイベントペイロード全体を含みます。
- CloudEvents仕様に準拠します。
- 真正性を保証するIndeed署名を含みます。
- 信頼性の高い配信のためのベストプラクティスに従います。
HTTPレスポンスコードの処理
次の表は、Webhookシステムがエンドポイントからのレスポンスコードをどのように処理するかを説明します。
| カテゴリ | HTTPコード | Webhookシステムの動作 | パートナーの対応 |
|---|---|---|---|
| 成功 |
| 配信完了としてマークします。リトライしません。 | 複雑な処理を行う前に応答します。 |
| リダイレクト |
| クライアントエラーとして扱います。 | エンドポイント設定を確認して修正します。 |
| クライアントエラー |
（ | クライアントエラーとして扱います。指数バックオフでリトライします。 | クライアント側のエン ドポイントの問題を修正します。設定の問題がないか速やかに調査します。 |
| レート制限エラー | 429 | レート制限ヘッダーを尊重します（対応するレート制限ヘッダーをご覧ください）。指定された遅延後にリトライします。アラートは発生しません。 | 対応不要です。レート制限は自動的に尊重されます。 |
| サーバーエラー |
| 指数バックオフでリトライします。 | サーバー側のエンドポイントの問題を修正します。 |
リトライの動作
Webhookシステムは、リトライによって信頼性の高い配信を保証します。
| 項目 | 値 |
|---|---|
| 最大リトライ回数 |
実質的に無制限のリトライ。 |
| 初回リトライ間隔 | 10ミリ秒 |
| バックオフ倍率 | 2.0 各試行後に間隔を倍にします。エラーコードの場合（ |
| 最大間隔 | 7,200秒（2時間） |
次の点を考慮してください。
- べき等性：同じイベントを複数回処理しても副作用がないようにWebhookハンドラーを設計します。
- 重複排除：イベントIDを使用して重複をフィルタリングします。
- 処理順序：イベントの到着順は前後する場合があります。順序付けにはタイムスタンプとIDを使用します。
Webhookリクエストの形式
Webhookシステムは、CloudEvents仕様を完全に実装しています。
| リクエスト | 説明 |
|---|---|
| メソッド | HTTP POST |
| Content-Type | application/cloudevents+json |
| ヘッダー |
|
| ボディ | CloudEvents形式のイベントデータを含むJSONペイロード。 |
| ボディ属性 |
|
Webhookシステムと連携する
求人ライフサイクルステータスイベントスキーマとデータスキーマについては、Jobs lifecycle events Webhookガイドをご覧ください。
パートナー連携チェックリスト
| 手順 | 説明 | 必須 |
|---|---|---|
| 1. | ✓ | |
| 2. | ||
| 3. | イベントを非同期で処理する。処理の前に速やかに | ✓ |
| 4. | ✓ | |
| 5. | ✓ | |
| 6. | ✓ | |
| 7. | 該当する場合は、レート制限ヘッダーに対応する。 | ✓ |
| 8. | ✓ |
1. 有効なSSL証明書を持つHTTPSエンドポイントを設定する
サーバー上にPOSTリクエストを 受信するHTTPSエンドポイントを作成します。本番Webhookエンドポイントは必ずHTTPSを使用してください。TLS v1.2およびv1.3に対応しています。
2. Webhook署名の検証を実装する
真正性を確保し、偽のイベントを防ぐため、X-Indeed-Signatureヘッダーを検証します。
署名ヘッダーの形式：
X-Indeed-Signature: <signature>3. イベントを非同期で処理する
- 受信後ただちに
2xxレスポンスを返します。 - タイムアウトを防ぐため、応答後にイベントを処理キューに入れます。
4. べき等なイベント処理にイベントIDを使用する
Webhookハンドラーがべき等になるよう設計します。リトライ、ネットワークの問題、手動リトライなどにより、イベントは複数回配信されることがあります。
重複に対応するには、次を実施します。
- 処理済みイベントの追跡にイベントIDを使用します。
- 重複した配信を安全に処理します。
- イベントの順序に依存しないようにします。
5. WebhookルートでCSRF保護を無効化する
WebフレームワークがCSRFトークンをチェックする場合、Webhookルートをこの保護から除外します。
6. 適切なステータスコードでエラーを処理する
適切なステータスコードを返します。
2xx：イベントを正常に受信しました。429：レート制限。Retry-Afterヘッダーを含めます。5xx：リトライが必要なサーバーエラー。
7. レート制限ヘッダーに対応する
対応しているレート制限ヘッダーの形式：
| ヘッダー | 説明 |
|---|---|
Retry-After | Webhookシステムは次のヘッダー形式に対応しています。
|
X-RateLimit | レート制限ウィンドウがリセットされるUNIXタイムスタンプ。 |
レート制限が検出され、ヘッダーがない場合：
- デフォルトの待機時間：3秒。
- 以降のリトライ：指数バックオフを使用します。
8. Webhook配信失敗をモニタリングしてアラートを出す
必要に応じて、Webhook配信をモニタリングします。
- 受信したすべてのWebhookをログに記録します。
- 処理の成功・失敗のメトリクスを追跡します。
- 繰り返し発生する失敗にアラートを出します。
サポート
Webhook連携のサポートは、次をご利用ください。
- Indeedの連携担当チームにお問い合わせください。
- CloudEvents仕様をご覧ください。