Webhook ガイド

Webhook を連携し、イベントをエンドポイントに配信します。

 

概要

Indeed の Webhook は、パートナーのエンドポイントにイベントを配信します。このガイドでは、Webhook の仕組み、連携方法、およびベストプラクティスについて説明します。

Webhook ワークフロー

1. 1.
   Webhook の仕組みを確認します。
2. 2.
   Webhook システムと連携します。

Webhook の仕組み

Webhook は、イベント通知を含む HTTP POST リクエストをエンドポイントに送信します。各配信には、次の特徴があります。

• JSON 形式の完全なイベントペイロードが含まれます
• CloudEvents specification を使用します
• 真正性を確認するための Indeed 署名が含まれます
• 信頼性の高い配信のベストプラクティスに従います

HTTP レスポンスコードの処理

この表では、エンドポイントから返される HTTP レスポンスコードを Webhook システムがどのように処理するかを説明します。

HTTP レスポンスコードの処理

カテゴリ	HTTP コード	Webhook システムのアクション	パートナーのアクション
成功	200 から 299	配信を完了としてマークします。再試行は行いません。	複雑な処理を実行する前にレスポンスを返します。
リダイレクト	300 から 399	クライアントエラーとして扱います。	エンドポイントの設定を確認し、修正します。
クライアントエラー	400 から 499 429 を除く	クライアントエラーとして扱います。指数バックオフを使用して再試行します。	クライアント側のエンドポイントの問題を修正します。設定の問題を迅速に調査します。
レート制限エラー	429	レート制限ヘッダーを尊重します（サポートされるレート制限ヘッダーを参照してください）。指定された遅延後に再試行します。アラートはトリガーされません。	対応は不要です。レート制限は自動的に尊重されます。
サーバーエラー	500 から 599	指数バックオフを使用して再試行します。	サーバー側のエンドポイントの問題を修正します。5xx エラーを監視し、根本原因を解決します。

再試行動作

Webhook システムは、再試行によって信頼性の高い配信を実現します。

再試行動作

特性	値
最大再試行回数	Integer.MAX_VALUE 実質的に無制限に再試行します。
初回再試行間隔	10 ミリ秒
バックオフ乗数	2.0 各試行後に間隔が 2 倍になります。エラーコードでは、指数バックオフを使用して再試行します（429 を除く）。
最大間隔	7,200 秒（2 時間）

次の点を考慮してください。

• べき等性: 副作用を発生させずに同じイベントを複数回処理できるように、Webhook ハンドラーを設計します。
• 重複排除: イベント ID を使用して重複を除外します。
• 処理順序: イベントは順不同で到着する場合があります。順序付けにはタイムスタンプと ID を使用します。

Webhook リクエスト形式

Webhook システムは、CloudEvents specification を完全に実装しています。

Webhook リクエスト形式

リクエスト	説明
メソッド	HTTP POST
Content-Type	application/cloudevents+json
ヘッダー	X-Indeed-Signature. 検証のための HMAC-SHA256 署名です。 Content-Type. CloudEvents のメディアタイプ: application/cloudevents+json.
ボディ	CloudEvents 形式のイベントデータを含む JSON ペイロードです。
ボディ属性	標準の CloudEvents 属性: id、source、type、time、datacontenttype、specversion。 idempotencykey: 重複排除とべき等処理に使用する一意の ID です。 data: イベントペイロードです。

Webhook システムと連携する

求人ライフサイクルステータスイベントのスキーマとデータスキーマについては、Jobs lifecycle events webhooks guide をご覧ください。

パートナー連携チェックリスト

パートナー連携チェックリスト

ステップ	説明	必須
1.	有効な SSL 証明書を持つ HTTPS エンドポイントを設定します。	✓
2.	Webhook 署名検証を実装します。
3.	イベントを非同期で処理します。処理前に、速やかに 2xx レスポンスを返します。	✓
4.	べき等イベント処理のためにイベント ID を使用します。	✓
5.	Webhook ルートの CSRF 保護を無効にします。	✓
6.	適切なステータスコードでエラーを処理します。	✓
7.	必要に応じて、レート制限ヘッダーをサポートします。	✓
8.	Webhook 配信の失敗を監視し、アラートを設定します。	✓

1. 有効な SSL 証明書を持つ HTTPS エンドポイントを設定する

サーバー上に、POST リクエストを受信する HTTPS エンドポイントを作成します。本番の Webhook エンドポイントでは HTTPS を使用する必要があります。TLS v1.2 および v1.3 をサポートしています。

2. Webhook 署名検証を実装する

真正性を確認し、偽のイベントを防ぐために、X-Indeed-Signature ヘッダーを検証します。

署名ヘッダーの形式:

X-Indeed-Signature: <signature>

3. イベントを非同期で処理する

1. 受信したら直ちに 2xx レスポンスを返します。
2. タイムアウトを防ぐために、レスポンスを返した後でイベントをキューに入れて処理します。

4. べき等イベント処理のためにイベント ID を使用する

Webhook ハンドラーは、べき等になるように設計します。イベントは、再試行、ネットワークの問題、または手動再試行によって複数回配信される場合があります。

重複に対応するには、次のようにします。

• イベント ID を使用して処理済みイベントを追跡します。
• 重複配信を安全に処理します。
• イベントの順序に依存しません。

5. Webhook ルートの CSRF 保護を無効にする

Web フレームワークで CSRF トークンを検証する場合は、Webhook ルートをこの保護の対象外にします。

6. 適切なステータスコードでエラーを処理する

適切なステータスコードを返します。

• 2xx: イベントを正常に受信したことを示します。
• 429: レート制限を示します。Retry-After ヘッダーを含めます。
• 5xx: 再試行が必要なサーバーエラーを示します。

7. レート制限ヘッダーをサポートする

サポートされるレート制限ヘッダーの形式:

サポートされるレート制限ヘッダー

ヘッダー	説明
Retry-After	Webhook システムでは、次のヘッダー形式をサポートしています。 Seconds: 整数です。待機する秒数を指定します。 Retry-After: 120 HTTP date: RFC 1123: Requirements for Internet Hosts -- Application and Support 形式の絶対タイムスタンプです。 Retry-After: Sat, 21 Oct 2023 07:28:00 GMT
X-RateLimit	レート制限ウィンドウがリセットされる UNIX タイムスタンプです。 X-RateLimit-Reset: 1609459200

レート制限が検出され、ヘッダーが存在しない場合は、次のように動作します。

• デフォルト待機時間: 3 秒です。
• 以降の再試行: 指数バックオフを使用します。

8. Webhook 配信の失敗を監視し、アラートを設定する

必要に応じて、Webhook 配信を監視します。

1. 受信したすべての Webhook をログに記録します。
2. 処理の成功または失敗のメトリクスを追跡します。
3. 繰り返し発生する失敗に対してアラートを設定します。

サポート

Webhook 連携のサポート:

• Indeed の連携担当チームにお問い合わせください。
• CloudEvents specification をご覧ください。

 

このページは役に立ちましたか？