Webhooksガイド
イベントをエンドポイントに配信するためにWebhookを連携します。
概要
IndeedのWebhookは、パートナーのエンドポイントにイベントを配信します。このガイドでは、Webhookの仕組み、連携、およびベストプラクティスについて説明します。
Webhookワークフロー
- 1.Webhookの仕組みを確認します。
- 2.Webhookシステムと連携する。
Webhookの仕組み
Webhookは、イベント通知を含むHTTP POSTリクエストをエンドポイントに送信します。各配信には、次の特徴があります。
- JSON形式の完全なイベントペイロードが含まれます。
- CloudEvents仕様を使用します。
- 真正性を確認するためのIndeed署名が含まれます。
- 信頼性の高い配信のベストプラクティスに従います。
HTTPレスポンスコードの処理
この表では、エンドポイントから返されるHTTPレスポンスコードをWebhookシステムがどのように処理するかを説明します。
| カテゴリ | HTTPコード | Webhookシステムのアクション | パートナーのアクション |
|---|---|---|---|
| 成功 |
| 配信を完了としてマークします。再試行は行いません。 | 複雑な処理を実行する前にレスポンスを返します。 |
| リダイレクト |
| クライアントエラーとして扱います。 | エンドポイントの設定を確認し、修正します。 |
| クライアントエラー |
（ | クライアントエラーとして扱います。指数バックオフを使用して再試行します。 | クライアント側のエンドポイントの問題を修正します。設定の問題を迅速に調査します。 |
| レート制限エラー | 429 | レート制限ヘッダーを尊重します。指定された遅延後に再試行します。アラートはトリガーされません。 | 対応は不要です。レート制限は自動的に尊重されます。 |
| サーバーエラー |
| 指数バックオフを使用して再試行します。 | サーバー側のエンドポイントの問題を修正します。 |
再試行動作
Webhookシステムは、再試行によって信頼性の高い配信を実現します。
| 特性 | 値 |
|---|---|
| 最大再試行回数 |
実質的に無制限に再試行します。 |
| 初回 再試行間隔 | 10ミリ秒 |
| バックオフ乗数 | 2.0 各試行後に間隔が2倍になります。エラーコード（ |
| 最大間隔 | 7,200秒（2時間） |
次の点を考慮してください。
- べき等性：副作用を発生させずに同じイベントを複数回処理できるように、Webhookハンドラーを設計します。
- 重複排除：イベントIDを使用して重複を除外します。
- 処理順序：イベントは順不同で到着する場合があります。順序付けにはタイムスタンプとIDを使用します。
Webhookリクエスト形式
Webhookシステムは、CloudEvents仕様を完全に実装しています。
| リクエスト | 説明 |
|---|---|
| メソッド | HTTP POST |
| Content-Type | application/cloudevents+json |
| ヘッダー |
|
| ボディ | CloudEvents形式のイベントデータを含むJSONペイロードです。 |
| ボディ属性 |
|
Webhookシステムと連携する
求人ライフサイクルステータスイベントのイベントスキーマとデータスキーマについては、求人ライフサイクルイベントの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をログに記録します。
- 処理の成功または失敗のメトリクスを追跡します。
- 繰り返し発生する失敗に対してアラートを設定します。
関連情報
- CloudEvents仕様
- レート制限ヘッダーについては、サポートされるレート制限ヘッダーをご覧ください。
サポート
Webhook連携のサポートについては、次をご覧ください。
- Indeedの連携担当チームにお問い合わせください。
- CloudEvents仕様をご覧ください。