Webhooksとの連携
はじめに
Webhooksを使用すると、アカウント内でイベントが発生した際に通知するURLを登録できます。イベントが発生すると、例えば成功したサブスクリプションが作成されると、Rokt CalendarはEventオブジェクトを作成します。このオブジェクトには、イベントの種類やそのイベントに関連するデータなど、イベントの発生に関するすべての重要な情報が含まれています。その後、Rokt CalendarはHTTP POSTリクエストを介して、アカウントのWebhooks設定にあるURLにEventオブジェクトを送信します。
Webhook設定の構成
Webhookは、Rokt CalendarアカウントのWebhook設定セクションで構成されます。 Add Webhookをクリックすると、Webhookを受け取るための新しいエンドポイントURLを追加するためのフォームが表示されます。また、購読するイベントのタイプも指定できます。
イベントを送信するために任意のURLを入力できますが、これはサーバー上の専用ページである必要があります。また、複数のイベントタイプに通知されるか、特定のイベントのみに通知されるかを選択することもできます。
サブスクリプションイベントの種類
- サブスクライブイベント: ユーザーがカレンダーにサブスクライブします。
- アンサブスクライブイベント: ユーザーがカレンダーのサブスクリプションを解除します。
Webhook v1 は廃止されています。古いWebhookバージョンは2つの基本的なイベントタイプのみをサポートしています。より多くのイベントタイプと最新のデータペイロード構造にはWebhook v2を使用してください。
よくあるWebhookの間違い
- ダッシュボードで間違ったURLを提供すること。
- Webhookエンドポイントが200のステータスコードを返さないこと。
Webhook通知の受信
サーバー上にWebhookエンドポイントを作成することは、ウェブサイト上の任意のページを作成することと同じです。 WebhookデータはPOSTリクエストのボディとしてJSON形式で送信されます。完全なイベントの詳細が含まれており、JSONをEventオブジェクトにパースした後、直接使用できます。
ウェブフックへの応答
ウェブフックの受信を確認するために、エンドポイントは2xxのHTTPステータスコードを返す必要があります。リクエストヘッダーやリクエストボディに返されるその他の情報は無視されます。3xxコードを含むこの範囲外のすべてのレスポンスコードは、ウェブフックを受信しなかったことをRokt Calendarに示します。これはURLリダイレクションや「変更されていません」の応答も失敗として扱われることを意味します。
任意の理由でウェブフックが正常に受信されない場合、Rokt Calendarは30分ごとに数分の間隔をおいてウェブフックを送信し続けます。
ダッシュボードを介して特定のイベント情報を表示する際に、ウェブフックの詳細セクションでエンドポイントのURLをクリックすることで、エンドポイントにイベントを送信しようと試みた回数を確認することができます。これにより、エンドポイントから受け取った最新のレスポンスと、試みられたすべてのウェブフックとそれぞれのHTTPステータスコードのリストが表示されます。30分が経過した後、ダッシュボードから失敗したイベントを再試行することもできます。
ベストプラクティス
ライブに移行する前に、Webhookが正常に動作していることをテストしてください。Webhookの設定画面からダミーテストイベントを送信することでテストできます。ただし、これらは偽のテストイベントであるため、アカウント内の実際のオブジェクトにはマッピングされません。
Webhookスクリプトが複雑なロジックを実行したり、ネットワーク呼び出しを行ったりする場合、Rokt Calendarが完全に実行される前にスクリプトがタイムアウトする可能性があります。そのため、Webhookエンドポイントは受信を即座に確認するために2xxのHTTPステータスコードを返し、その後の処理を行うことが望ましいです。
Webhookエンドポイントは、同じイベントを複数回受信することがあります。イベントの重複受信に対しては、イベント処理を冪等性にすることで防御することをお勧めします。これを行う方法の一つは、処理済みのイベントをログに記録し、既にログに記録されたイベントを処理しないようにすることです。