第15章 Webhook

本章では、デベロッパーポータル で Webhook を設定し、操作を行う方法について説明します。

Webhook を使用すると、3scale をバックオフィスのワークフローと密接に連携させることができます。3scale システムで指定のイベントが発生すると、Webhook メッセージによりアプリケーションに通知が届き、新規アカウントのサインアップからのデータなどを使用して、デベロッパーポータルに反映させることができます。

15.1. Webhook の概要

Webhook は、Webhook 設定ウィンドウで利用可能なイベントから選択されたイベントによってトリガーされるカスタム HTTP コールバックです。これらのイベントのいずれかが発生すると、3scale システムは、Webhook セクションで指定した URL アドレスに対して HTTP または HTTPS リクエストを行います。API プロバイダー側では、リスナーを設定してイベント追跡などの目的の動作を呼び出すことができます。

Webhook を設定するには、以下の手順を実施します。

  1. Account Settings > Integrate > Webhooks の順に移動します。Account Settings は、ウィンドウの右上にある歯車アイコンです。
  2. Webhook の動作を指定します。2 つのオプションがあります。

    • Webhooks enabled: Webhook を有効または無効にするには、このチェックボックスを選択します。
    • Actions in the admin portal also trigger webhooks: イベント発生時に Webhooks をトリガーするには、このチェックボックスを選択します。以下の点を考慮してください。

      • トリガーとなるイベントが設定された内部 3scale API への呼び出しを行う場合は、プロバイダーキーではなくアクセストークンを使用します。
      • このチェックボックスを選択しないままにすると、デベロッパーポータルのアクションだけが Webhook のトリガーになります。
  3. 選択したイベントがトリガーとなった際にイベントを通知するための URL アドレスを指定します。
  4. 指定した URL アドレスへのコールバックのトリガーとなるイベントを選択します。

設定が完了したら、Update webhooks settings をクリックして変更を保存します。

15.2. Webhook のフォーマット

Webhook のフォーマットは常に同じです。以下の構造の XML ドキュメントでエンドポイントにポストします。

<?xml version="1.0" encoding="UTF-8"?>
<event>
  <type>application</type>
  <action>updated</action>
  <object>
    THE APPLICATION OBJECT AS WOULD BE RETURNED BY A GET ON THE ACCOUNT MANAGEMENT
    API
  </object>
</event>

各要素では、以下の情報を提供します。

  • <type>: applicationaccount など、イベントの主体を表します。
  • <action>: updatedcreateddeleted などの値を使用してアクションを指定します。
  • <object>: Account Management API によって返される、同じフォーマットの XML オブジェクト自体です。インタラクティブな ActiveDocs を使用して確認できます。

Webhook が 3scale によって実行されたことを保証する必要がある場合は、HTTPS Webhook URL を公開し、3scale の Webhook 宣言にカスタムパラメーターを追加します。たとえば、https://your-webhook-endpoint?someSecretParameterName=someSecretParameterValue となります。パラメーター名と値を指定します。続いて、Webhook エンドポイント内で、このパラメーター値があることを確認します。

15.3. トラブルシューティング

リッスンしているエンドポイントに障害が発生した場合、失敗した配信を回復できます。エンドポイントがコード 200 を返す場合に、3scale は Webhook が配信されたとみなします。そうでない場合は、60 秒間隔で 5 回リトライします。障害からの復旧後に、または定期的にチェックを実行し、必要に応じキューをクリーンアップする必要があります。ActiveDocs では、以下のメソッドの詳細情報を確認できます。

  • 配信に失敗した Webhook の一覧
  • 配信に失敗した Webhook の削除