最終更新日 2025年01月09日(木)

アプリの Webhook を使用すると、Heroku アプリに特定の変更が加えられた場合は常に通知を受信できます。次のような、さまざまなイベントの通知を購読できます。

• ドメインの設定への変更
• アプリのビルド
• アプリのリリース
• アドオンの変更
• Dyno formation の変更

Webhook 通知は、希望する URL への HTTP POST リクエストとして送信されます。Webhook と統合するには、これらのリクエストを受信して処理するサーバーエンドポイントを実装する必要があります。

はじめに

できるだけ早く開始するには、Dashboard の Webhook インターフェースに移動するか、またはアプリの Webhook のチュートリアル​に従ってください。そこでは、CLI で単純な Webhook サブスクリプションを作成する方法が説明されています。

そのチュートリアルを完了したら、この記事に戻り、Webhook を購読して通知を受信する方法についての詳細を参照してください。

Dashboard を使用した Webhook の購読

アプリの “Dashboard” (ダッシュボード) ページに移動し、"More" (詳細) の下のドロップダウンメニューを表示します。"View Webhooks" (Webhook の表示) オプションが表示されます。これをクリックすると、Webhook の作成および管理インターフェースが表示されます。

Heroku CLI を使用した Webhook の購読

手順 1: Heroku CLI を更新する

手順 2: どのイベントを購読するかを決定する

手順 3: 購読する

再試行と制限

Webhook API を使用した購読

Webhook 通知を購読するには、Webhook API の Webhook の作成​エンドポイントを使用します。必須パラメータとオプションパラメータの一覧については、そのリファレンスを参照してください。これらのパラメータほとんどは、CLI を使用して購読する場合に使用できるパラメータに対応しています。

Webhook リクエストのセキュリティ保護

共有秘密鍵の使用

リクエストが Heroku から来ていることを証明するには、Webhook 作成の秘密鍵をリクエストヘッダーと組み合わせて使用して、そのリクエストが共有秘密鍵によって署名されたことを確認します。リクエストと秘密鍵を取得し、そのリクエストが Heroku から来ているかどうかを判定する Ruby on Rails のいくつかのサンプルコードを次に示します。webhook_secret​ パラメータはアプリケーションコード内ではなく、Heroku 環境設定などの安全な場所に保存します。

  def valid_signature?(request, webhook_secret)
    calculated_hmac = Base64.encode64(OpenSSL::HMAC.digest(
      OpenSSL::Digest.new('sha256'),
      webhook_secret,
      request.raw_post
    )).strip
    heroku_hmac = request.headers['Heroku-Webhook-Hmac-SHA256']

    heroku_hmac && Rack::Utils.secure_compare(calculated_hmac, heroku_hmac)
  end

共有承認の使用

リクエストが Heroku から来ていることを確認するために承認フラグを使用することもできます。設定されている場合、この承認値はリクエスト内の Authorization​ ヘッダーに渡されます。この共有秘密鍵は変更なしで渡されるため、選択した承認メカニズムを使用して検証します。

サブスクリプションの管理

サブスクリプションを作成した後、それを確認したり、削除したりすることもできます。

Webhook の一覧表示​エンドポイントまたは CLI を使用して、アクティブな Webhook サブスクリプションを一覧表示できます。

$ heroku webhooks

Webhook の削除​エンドポイントまたは heroku webhooks:remove​ CLI コマンドを使用して、Webhook サブスクリプションを削除できます。

Webhook の受信

購読している Webhook イベントが発生した場合、Heroku は、そのイベントの詳細を含むサーバーエンドポイントに POST リクエストを送信します。これらのリクエストの正当性は、次の方法で確認できます。

• リクエストの Authorization​ ヘッダーが、通知を購読するときに指定した値に一致している。
• リクエストの Heroku-Webhook-Hmac-SHA256​ ヘッダーに、リクエスト本体の (購読するときに指定した secret​ 値で署名された) HMAC SHA256 署名が含まれている。

結果として得られる Webhook 通知リクエストは次のようになります。

POST https://example.com/hooks
Authorization: Bearer 01234567-89ab-cdef-0123-456789abcdef
Heroku-Webhook-Hmac-SHA256: cLM15U5x+jHEkANnVasRwBw2yEHu94pXdjcT9Hajc1M=

{
  "action": "update",
  "actor": {
    "email": "user-0436@example.com",
    "id": "096370c8-f3ad-4e20-a309-fb4f06ec0a89"
  },
  "created_at": "2016-10-26T22:50:14Z",
  "id": "d472a8bb-1a3c-4f78-aad1-995e6d0022ec",
  "data": {
    "archived_at": null,
    "buildpack_provided_description": "Ruby/Rails",
    "build_stack": {
      "id": "5e854079-da33-475b-a209-77f527c0e2fb",
      "name": "heroku-18"
    },
    "created_at": "2016-10-26T22:50:14Z",
    "id": "d4714cc8-aa56-4314-817c-0c6a66ff3d41",
    "git_url": "https://git.heroku.com/sample-app-0301.git",
    "maintenance": false,
    "name": "sample-app-0301",
    "owner": {
      "email": "user-0436@example.com",
      "id": "096370c8-f3ad-4e20-a309-fb4f06ec0a89"
    },
    "region": {
      "id": "7044c05a-0873-42c2-abbe-6841c5481ba7",
      "name": "us"
    },
    "organization": null,
    "space": null,
    "released_at": "2016-10-26T22:50:14Z",
    "repo_size": 1048576,
    "slug_size": null,
    "stack": {
      "id": "5e854079-da33-475b-a209-77f527c0e2fb",
      "name": "heroku-18"
    },
    "updated_at": "2016-10-26T22:50:14Z",
    "web_url": "https://sample-app-0301.herokuapp.com/"
  },
  "previous_data": {
  },
  "published_at": null,
  "resource": "app",
  "sequence": null,
  "updated_at": "2016-10-26T22:50:14Z",
  "version": "application/vnd.heroku+json; version=3",
  "webhook_metadata": {
    "attempt": {
      "id": "8a44f820-2354-489d-9a11-a793cbf49979"
    },
    "delivery": {
      "id": "d244009a-670f-4340-88e9-789a4f9002d5"
    },
    "event": {
      "id": "d472a8bb-1a3c-4f78-aad1-995e6d0022ec",
      "include": "api:app"
    },
    "webhook": {
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  }
}

通知を受信したことを示すには、常に 200 レベルのステータスコードで応答します。Heroku では応答の本体が無視されるため、空の本体を持つ 204​ ステータスが理想的です。

204 No Content

$ heroku webhooks:deliveries

sync​ の通知レベルで購読した場合、成功するか、または再試行カウントがなくなるまで、Heroku は失敗したリクエストを再試行します。

配信ステータスの確認

Heroku が送信のためにキューに入れている通知のログを表示できます。各通知には status​ (pending​、success​、failure​、skipped​ のいずれか) があり、これを確認することによって通知の配信の現在のヘルスを監視できます。

CLI を使用した配信の内観

次のコマンドを実行してください。

$ heroku webhooks:deliveries

Webhook API を使用した配信の内観

配信の一覧表示エンドポイント​を使用します。

過去のイベントの検索

以前に送信された配信の id​ がある場合は、そのイベントの詳細をもう一度フェッチできます。

CLI を使用したイベントの内観

次のコマンドを実行してください。

$ heroku webhooks:deliveries:info DELIVERY_ID

Webhook API を使用したイベントの内観

イベントの情報エンドポイント​を使用します。