旧バージョンのドキュメントを参照しています。最新のドキュメントはこちらをご参照ください。

イベントフックのリファレンス

イベントフックはKong Gatewayからのアウトバウンドコールです。イベントフックを使用すると、Kong Gateway はターゲットのサービスやリソースと通信して、イベントがトリガーされたことをターゲットに知らせます。Kongでイベントがトリガーされると、そのイベントに関する情報を含むURLが呼び出されます。イベントフックは、管理インターフェースを使用してワーカーイベントをサブスクライブするための構成レイヤーを追加します。ワーカーイベントは、ゲートウェイコンテキスト内で通信するためにKong Gatewayに統合されます。たとえば、エンティティが作成されると、 Kong Gatewayはエンティティに関する情報を含むイベントを発生させます。Kong Gateway コードベースの一部はこれらのイベントをサブスクライブし、コールバックを使用してイベントを処理できます。

Kong Gatewayでは、これらのコールバックは以下のいずれかの「ハンドラ」を使用して定義できます。

webhook： イベントデータをペイロードとして、指定されたURLにJSON POSTリクエストを行います。中間層の統合（Kongフックを受信する独自のwebhook）を構築する場合に役立ちます。リクエストに対して特定のヘッダーを構成できます。
webhook-custom： 完全に設定可能なリクエスト。サービス（Slack webhook など）があり、直接統合の構築に便利です。完全に構成可能であるため、設定がより複雑です。構成可能な本文、構成可能な形式のペイロード、およびヘッダーをサポートしています。
ログ: このハンドラは構成が不要で、イベントとペイロードの内容を Kong Gateway ログに記録します。ハイブリッドモードを使用している場合、crud および dao:crud のソースのログはコントロールプレーン（CP）のログに出力され、balancer および rate-limiting-advanced のソースのログはデータプレーンのログに出力されます。
lambda： このハンドラは、イベントのトリガー後に、指定されたLuaコードを実行します。

注: 現時点でイベントフックは Konnect では動作しません。

すべてのイベントフックを一覧表示する

エンドポイント

/event\-hooks

応答

{
    "data": [
        {
            "config": {
                "body": null,
                "body_format": true,
                "headers": {
                    "content-type": "application/json"
                },
                "headers_format": false,
                "method": "POST",
                "payload": {
                    "text": "Admin account \`{{ entity.username }}\` {{ operation}}d; email address set to \`{{ entity.email }}\`"
                },
                "payload_format": true,
                "secret": null,
                "ssl_verify": false,
                "url": "https://hooks.slack.com/services/foo/bar/baz"
            },
            "created_at": 1627588552,
            "event": "admins",
            "handler": "webhook-custom",
            "id": "937df175-3db2-4e6d-8aa1-d95c94a76089",
            "on_change": null,
            "snooze": null,
            "source": "crud"
        },
        {
            "config": {
                "headers": {},
                "secret": null,
                "ssl_verify": false,
                "url": "https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6"
            },
            "created_at": 1627581575,
            "event": "consumers",
            "handler": "webhook",
            "id": "c57340ab-9fed-40fd-bb7e-1cef8d37c2df",
            "on_change": null,
            "snooze": null,
            "source": "crud"
        },
        {
            "config": {
                "functions": [
                    "return function (data, event, source, pid)\n  local user = data.entity.username\n  error(\"Event hook on consumer \" .. user .. \"\")\nend\n"
                ]
            },
            "created_at": 1627595513,
            "event": "consumers",
            "handler": "lambda",
            "id": "c9fdd58d-5416-4d3a-9467-51e5cfe4ca0e",
            "on_change": null,
            "snooze": null,
            "source": "crud"
        }
    ],
    "next": null
}

すべてのソースを一覧表示する

ソースは、イベントフックをトリガーするアクションです。/sourcesのJSON出力は次のパターンに従います。

1レベル = ソース。このソースはイベントフックをトリガーするアクションです。
第2のレベル = イベントフックがイベントをリッスンする Kongエンティティのイベント。
3 番目のレベル = Webhook カスタムペイロードで使用可能なテンプレートパラメータ。

たとえば、次の例では、balancer がソース、health がイベント、upstream_id、ip、port、hostname、health が使用可能なテンプレートパラメーターです。

エンドポイント

/event\-hooks/sources/

応答

{
    "data": {
        "balancer": {
            "health": {
                "fields": [
                    "upstream_id",
                    "ip",
                    "port",
                    "hostname",
                    "health"
                ]
            }
        },
        "crud": {
            "acls": {
                "fields": [
                    "operation",
                    "entity",
                    "old_entity",
                    "schema"
                ]
            },
            . . .

        "rate-limiting-advanced": {
            "rate-limit-exceeded": {
                "description": "Run an event when a rate limit has been exceeded",
                "fields": [
                    "consumer",
                    "ip",
                    "service",
                    "rate",
                    "limit",
                    "window"
                ],
                "unique": [
                    "consumer",
                    "ip",
                    "service"
                ]
            }
        }
    }
}

注：全文を掲載するには長すぎるため、レスポンスは短縮されています。レスポンスの中央にある省略記号は、欠落しているコンテンツを表します。

ソースのすべてのイベントを一覧表示

イベントは、イベントフックがイベントをリッスンする Kong エンティティです。このエンドポイントを使用すると、特定のソースに関連付けられたすべてのイベントを一覧表示できます。

/event\-hooks/sources/\{source\}/

次のレスポンスは、dao:crud ソースのすべてのイベントを一覧表示します。

応答

{
    "data": {
        "create": {
            "fields": [
                "operation",
                "entity",
                "old_entity",
                "schema"
            ]
        },
        "delete": {
            "fields": [
                "operation",
                "entity",
                "old_entity",
                "schema"
            ]
        },
        "update": {
            "fields": [
                "operation",
                "entity",
                "old_entity",
                "schema"
            ]
        }
    }
}

webhookを追加する

エンドポイント

/event\-hooks

リクエストボディ

属性	説明
`event` オプション	イベントフックがイベントをリッスンするKongエンティティについて説明する文字列。
`handler` 必須	webhook、webhook-custom、log、lambdaの4つのハンドラオプションのいずれかを説明する文字列。
`source` 必須	イベントフックをトリガーするアクションを説明する文字列。
`snooze` オプション	イベントトリガーの遅延時間を秒単位で記述する任意の整数で、統合のスパムを回避する目的があります。
`on_change` オプション	ペイロードのキー部分に変更があった場合に、イベントをトリガーするかどうかを示すオプションのブール値。
`config.url` 必須	イベントデータをペイロードとしてJSON POSTリクエストが行われるURL。
`config.headers` オプション	Webhookリクエストで送信する追加のHTTPヘッダーを定義するオブジェクト（例：`{"X-Custom-Header": "My Value"}` ）
`config.secret` オプション	リモート検証のためにリモート webhook への署名で使用されるオプションの文字列。設定すると、Kong はイベントフックのボディを HMAC-SHA1 で署名し、それをリモートエンドポイントへのヘッダー `x-kong-signature` に含めます。
`config.ssl_verify` オプション	イベントフックが送信されるリモートHTTPSサーバーのSSL証明書を検証するかどうかを示すブール値。デフォルトは `false` です。

応答

{
    "config": {
        "headers": {},
        "secret": null,
        "ssl_verify": false,
        "url": "https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6"
    },
    "created_at": 1627581575,
    "event": "consumers",
    "handler": "webhook",
    "id": "c57340ab-9fed-40fd-bb7e-1cef8d37c2df",
    "on_change": null,
    "snooze": null,
    "source": "crud"
}

カスタムwebhookの追加

エンドポイント

/event\-hooks

リクエストボディ

属性	説明
`event` オプション	イベントフックがイベントをリッスンするKongエンティティについて説明する文字列。
`handler` 必須	webhook、webhook-custom、log、lambdaの4つのハンドラオプションのいずれかを説明する文字列。
`source` 必須	イベントフックをトリガーするアクションを説明する文字列。
`snooze` オプション	イベントトリガーの遅延時間を秒単位で記述する任意の整数で、統合のスパムを回避する目的があります。
`on_change` オプション	ペイロードのキー部分に変更があった場合に、イベントをトリガーするかどうかを示すオプションのブール値。
`config.url` 必須	イベントデータをペイロードとしてJSON POSTリクエストが行われるURL。
`config.method` 必須	カスタムwebhookの作成に使用されるHTTPメソッド。
`config.payload` オプション	構成可能なペイロード本文を記述するキーと値のペアを含むオブジェクト。テンプレートをサポートします。使用可能なテンプレートパラメータの完全なリストは、 `/sources` API出力の`fields` JSONオブジェクトにあります。
`config.payload_format` オプション	restyテンプレート法で`config.payload`を書式設定するかどうかを示すオプションのブール値（デフォルトは`true`）`false`に設定すると、ペイロードは生のオブジェクトとして送信されます。
`config.body` オプション	リモートリクエストで送信されるオプションの文字列。
`config.body_format` オプション	restyテンプレート法で`config.body`を書式設定するかどうかを示すオプションのブール値（デフォルトは`true`）`false`に設定すると、ボディは生のオブジェクトとして送信されます。特定の`source`に定義されている使用可能なすべてのパラメータを確認するには、`/event-hooks/source`エンドポイントによって表示されるソースフィールドを確認します。
`config.headers`	Webhookリクエストで送信する追加のHTTPヘッダーを定義するオブジェクト（例：`{"Content-type": "application/json", "X-Custom-Header": "My Value"}` ）
`config.headers_format` オプション	restyテンプレート法で`config.headers`を書式設定するかどうかを示すオプションのブール値（デフォルトは`false`）`true`に設定すると、 `config.headers`値はテンプレートとして扱われます。特定の`source`に定義されている使用可能なすべてのパラメータを確認するには、 `/event-hooks/sources`エンドポイントによって表示されるソースフィールドを確認します。
`config.secret` オプション	リモート検証のためにリモート webhook への署名で使用されるオプションの文字列。設定すると、Kong はイベントフックのボディを HMAC-SHA1 で署名し、それをリモートエンドポイントへのヘッダー `x-kong-signature` に含めます。
`config.ssl_verify` オプション	イベントフックが送信されるリモートHTTPSサーバーのSSL証明書を検証するかどうかを示すブール値。デフォルト値は`false`です。

応答

{
    "config": {
        "body": null,
        "body_format": true,
        "headers": {
            "content-type": "application/json"
        },
        "headers_format": false,
        "method": "POST",
        "payload": {
            "text": "Admin account `` d; email address set to ``"
        },
        "payload_format": true,
        "secret": null,
        "ssl_verify": false,
        "url": "https://hooks.slack.com/services/foo/bar/baz"
    },
    "created_at": 1627588552,
    "event": "admins",
    "handler": "webhook-custom",
    "id": "937df175-3db2-4e6d-8aa1-d95c94a76089",
    "on_change": null,
    "snooze": null,
    "source": "crud"
}

ログイベントフックを追加する

エンドポイント

/event\-hooks

リクエストボディ

属性	説明
`event` オプション	イベントフックがイベントをリッスンするKongエンティティについて説明する文字列。
`handler` 必須	webhook、webhook-custom、log、lambdaの4つのハンドラオプションのいずれかを説明する文字列。
`source` 必須	イベントフックをトリガーするアクションを説明する文字列。
`snooze` オプション	イベントトリガーの遅延時間を秒単位で記述する任意の整数で、統合のスパムを回避する目的があります。
`on_change` オプション	ペイロードのキー部分に変更があった場合に、イベントをトリガーするかどうかを示すオプションのブール値。

応答

{
  "config": {},
  "on_change": null,
  "created_at": 1627346155,
  "snooze": null,
  "id": "13a16f91-68b6-4384-97f7-d02763a551ac",
  "handler": "log",
  "source": "crud",
  "event": "routes"
}

Lambdaイベントフックの追加

エンドポイント

/event\-hooks

リクエストボディ

属性	説明
`event` オプション	イベントフックがイベントをリッスンするKongエンティティについて説明する文字列。
`handler` 必須	webhook、webhook-custom、log、lambdaの4つのハンドラオプションのいずれかを説明する文字列。
`source` 必須	イベントフックをトリガーするアクションを説明する文字列。
`snooze` オプション	イベントトリガーの遅延時間を秒単位で記述する任意の整数で、統合のスパムを回避する目的があります。
`on_change` オプション	ペイロードのキー部分に変更があった場合に、イベントをトリガーするかどうかを示すオプションのブール値。
`config.functions` 必須	イベントフックで実行する Lua コード関数の配列。

応答

{
    "config": {
        "functions": [
            "return function (data, event, source, pid)\n  local user = data.entity.username\n  error(\"Event hook on consumer \" .. user .. \"\")\nend\n"
        ]
    },
    "created_at": 1627595513,
    "event": "consumers",
    "handler": "lambda",
    "id": "c9fdd58d-5416-4d3a-9467-51e5cfe4ca0e",
    "on_change": null,
    "snooze": null,
    "source": "crud"
}

イベントフックのテスト

イベントをトリガーせずに、イベントフックを手動でトリガーすると便利です。たとえば、統合をテストしたり、フックのサービスが Kong からペイロードを受信しているかどうかを確認したい場合があります。

任意のデータを/event-hooks/:id-of-hook/testにPOSTすると、/testエンドポイントは提供されたデータをイベントペイロードとして実行します。

エンドポイント

/event\-hooks/\{event\-hook\-id\}/test

応答

{
    "data": {
        "consumer": {
            "username": "Jane Austen"
        },
        "event": "consumers",
        "source": "crud"
    },
    "result": {
        "body": "",
        "headers": {
            "Cache-Control": "no-cache, private",
            "Content-Type": "text/plain; charset=UTF-8",
            "Date": "Fri, 30 Jul 2021 16:07:09 GMT",
            "Server": "nginx/1.14.2",
            "Transfer-Encoding": "chunked",
            "Vary": "Accept-Encoding",
            "X-Request-Id": "f1e703a5-d22c-435c-8d5d-bc9c561ead4a",
            "X-Token-Id": "1cc1c53b-f613-467f-a5c9-20d276405104"
        },
        "status": 200
    }
}

webhookイベントフックのネット接続の確認

エンドポイント

/event\-hooks/\{event\-hook\-id\}/ping

応答

{
  "source": "kong:event_hooks",
  "event_hooks": {
    "source": "crud",
    "id": "c57340ab-9fed-40fd-bb7e-1cef8d37c2df",
    "on_change": null,
    "event": "consumers",
    "handler": "webhook",
    "created_at": 1627581575,
    "config": {
      "headers": {
        "content-type": "application/json"
      },
      "ssl_verify": false,
      "url": "https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6",
      "secret": null
    },
    "snooze": null
  },
  "event": "ping"
}