Event Hooks Reference

    Event hooks are outbound calls from Kong Gateway. With event hooks, the Kong Gateway can communicate with target services or resources, letting the target know that an event was triggered. When an event is triggered in Kong, it calls a URL with information about that event. Event hooks add a layer of configuration for subscribing to worker events using the admin interface. Worker events are integrated into Kong Gateway to communicate within the gateway context. For example, when an entity is created, the Kong Gateway fires an event with information about the entity. Parts of the Kong Gateway codebase can subscribe to these events, then process the events using callbacks.

    In Kong Gateway, these callbacks can be defined using one of the following “handlers”:

    • webhook: Makes a JSON POST request to a provided URL with the event data as a payload. Useful for building a middle tier integration (your own webhook that receives Kong hooks). Specific headers can be configured for the request.

    • webhook-custom: Fully configurable request. Useful for building a direct integration with a service (for example, a Slack webhook). Because it’s fully configurable, it’s more complex to configure. It supports templating on a configurable body, a configurable form payload, and headers.

    • log: This handler, which requires no configuration, logs the event and the content of the payload into the Kong Gateway logs. If using hybrid mode, the and dao:crud sources will log on the control plane logs and the balancer and rate-limiting-advanced sources will log on the data plane logs.

    • lambda: This handler runs specified Lua code after an event is triggered.

    Endpoint

    /event-hooks

    Response

    List all sources

    Sources are the actions that trigger the event hook. The /sources JSON output follows the following pattern:

    • 1st level = The source, which is the action that triggers the event hook.
    • 2nd level = The event, which is the Kong entity the event hook will listen to for events.
    • 3rd level = The available template parameters for use in webhook-custom payloads.

    For instance, in the example below balancer is the source, health is the event, and upstream_id, ip, port, hostname, and health are the available template parameters.

    Endpoint

    /event-hooks/sources/

    1. {
    2.     "data": {
    3.         "balancer": {
    4.             "health": {
    5.                 "fields": [
    6.                     "upstream_id",
    7.                     "ip",
    8.                     "port",
    9.                     "hostname",
    10.                     "health"
    11.                 ]
    12.             }
    13.         },
    14.         "crud": {
    15.             "acls": {
    16.                 "fields": [
    17.                     "operation",
    18.                     "entity",
    19.                     "old_entity",
    20.                     "schema"
    21.                 ]
    22.             },
    23.             . . .
    25.         "rate-limiting-advanced": {
    26.             "rate-limit-exceeded": {
    27.                 "description": "Run an event when a rate limit has been exceeded",
    28.                 "fields": [
    29.                     "consumer",
    30.                     "ip",
    31.                     "service",
    32.                     "rate",
    33.                     "limit",
    34.                     "window"
    35.                 ],
    36.                 "unique": [
    37.                     "consumer",
    38.                     "ip",
    39.                     "service"
    40.             }
    41.         }
    42.     }
    43. }

    List all events for a source

    Events are the Kong entities the event hook will listen to for events. With this endpoint you can list all of the events associated with a particular source.

    /event-hooks/sources/{source}/

    The following response lists all of the events for the dao:crud source.

    Response

    1. {
    2.     "data": {
    3.         "create": {
    4.             "fields": [
    5.                 "operation",
    6.                 "entity",
    7.                 "old_entity",
    8.                 "schema"
    9.             ]
    10.         },
    11.         "delete": {
    12.             "fields": [
    13.                 "operation",
    14.                 "entity",
    15.                 "old_entity",
    16.                 "schema"
    17.             ]
    19.         "update": {
    20.             "fields": [
    21.                 "operation",
    22.                 "entity",
    23.                 "old_entity",
    24.                 "schema"
    25.             ]
    26.         }
    27.     }
    28. }

    Endpoint

    /event-hooks

    Request Body

    Response

    Add a custom webhook

    Endpoint

    /event-hooks

    Request Body

    Response

    1. {
    2.     "config": {
    3.         "body": null,
    4.         "body_format": true,
    5.         "headers": {
    6.             "content-type": "application/json"
    7.         },
    8.         "headers_format": false,
    9.         "method": "POST",
    10.         "payload": {
    11.             "text": "Admin account `` d; email address set to ``"
    12.         },
    13.         "payload_format": true,
    14.         "secret": null,
    15.         "ssl_verify": false,
    16.         "url": "https://hooks.slack.com/services/foo/bar/baz"
    17.     },
    19.     "event": "admins",
    20.     "handler": "webhook-custom",
    21.     "id": "937df175-3db2-4e6d-8aa1-d95c94a76089",
    22.     "on_change": null,
    23.     "snooze": null,
    24. }

    Add a log event hook

    Endpoint

    Request Body

    Response

    1. {
    2.   "config": {},
    3.   "on_change": null,
    4.   "created_at": 1627346155,
    5.   "snooze": null,
    6.   "id": "13a16f91-68b6-4384-97f7-d02763a551ac",
    7.   "handler": "log",
    8.   "source": "crud",
    9.   "event": "routes"
    10. }

    Endpoint

    /event-hooks

    Request Body

    Response

    Test an event hook

    It’s useful to manually trigger an event hook without provoking the event to be triggered. For instance, you might want to test the integration, or see if your hook’s service is receiving a payload from Kong.

    POST any data to /event-hooks/:id-of-hook/test, and the /test endpoint executes the with the provided data as the event payload.

    Endpoint

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

    Response

    1. {
    2.     "data": {
    3.         "consumer": {
    4.             "username": "Jane Austen"
    5.         },
    6.         "event": "consumers",
    7.         "source": "crud"
    8.     },
    9.     "result": {
    10.         "body": "",
    11.         "headers": {
    12.             "Cache-Control": "no-cache, private",
    13.             "Content-Type": "text/plain; charset=UTF-8",
    14.             "Date": "Fri, 30 Jul 2021 16:07:09 GMT",
    15.             "Server": "nginx/1.14.2",
    16.             "Transfer-Encoding": "chunked",
    17.             "Vary": "Accept-Encoding",
    18.             "X-Request-Id": "f1e703a5-d22c-435c-8d5d-bc9c561ead4a",
    19.             "X-Token-Id": "1cc1c53b-f613-467f-a5c9-20d276405104"
    20.         },
    21.         "status": 200
    22.     }
    23. }

    Ping a webhook event hook

    Endpoint

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

    Response

    1. {
    2.   "source": "kong:event_hooks",
    3.   "event_hooks": {
    4.     "source": "crud",
    5.     "id": "c57340ab-9fed-40fd-bb7e-1cef8d37c2df",
    6.     "on_change": null,
    7.     "event": "consumers",
    8.     "handler": "webhook",
    9.     "created_at": 1627581575,
    10.     "config": {
    11.       "headers": {
    12.         "content-type": "application/json"
    13.       },
    14.       "ssl_verify": false,
    15.       "url": "https://webhook.site/a1b2c3-d4e5-g6h7-i8j9-k1l2m3n4o5p6",
    16.       "secret": null
    17.     },
    18.     "snooze": null
    19.   },
    20.   "event": "ping"