Event Hooks

An Event Hook is a Kong Gateway entity that can be configured to listen for specific events from Kong Gateway entities. An Event Hook can be configured to send information to logs, webhooks, or third-party applications.

Kong Gateway Event Hooks work by configuring the following three elements:

• Sources: The actions or operation that trigger the Event Hook.
• Events: The Kong Gateway entity that the Event Hook monitors for actions.
• Handlers: The mechanism that defines what action is performed when an event is triggered, like sending a webhook, logging, or executing custom code.

 
flowchart LR
    subgraph events [Kong Gateway Events]
        A(Gateway Service
Create
Delete
Modify)
        B(Admins
Create
Delete
Modify)
    end 

    subgraph handlers [Handlers]
        C(Webhook)
        D(logs
)
        E(webhook-custom)
        F(Lambda)
    end

    subgraph output [Output]
        W( POST to third party application)
        X( Log to /usr/local/kong/logs/error.log)
        Y( POST to third party application
Fully customizable)
        Z( Custom Code Lua code )
    end
    
    A --> handlers
    B --> handlers

    C --> W
    D --> X
    E --> Y
    F --> Z 
  

Handlers

There are four types of handlers that can be used with Event Hooks:

• webhook: Issues a POST request to a provided URL with the event data as a payload.
• log: Logs the event and the content of the payload as a Kong Gateway log.
• webhook-custom: Fully configurable request. Supports templating, configurable body, payload, and headers.
• lambda: This handler runs Lua code after an event is triggered.

By default, the lambda handler is “Sandboxed”. Sandboxing means that Kong Gateway restricts the types of Lua functions that can be loaded as well as the level of access to Kong Gateway that is available for these custom functions. For example, in sandbox mode, a lambda Event Hook will not have access to global values such as kong.configuration.pg_password, or OS level functions like os.execute(rm -rf /*), but can still run Lua code like local foo = 1 + 1. Removing sandbox requires editing the kong.conf value untrusted_lua, for more information see the kong.conf documentation.

Sources

Kong Gateway offers the /event-hooks/sources endpoint where you can see all available sources, events and fields that are available for creating Event Hook templates. Sources are the actions that trigger the Event Hook.

The response body from the endpoint describes a source that can be interpreted in the following pattern:

1. Level 1: The source, the action that triggers the Event Hook.
2. Level 2: The event, this is the Kong Gateway entity that the Event Hook listens to for events.
3. Level 3: The available template parameters for constructing webhook-custom payloads.

This is an example response body:

{
	"data": {
		"balancer": {
			"health": {
				"fields": [
					"upstream_id",
					"ip",
					"port",
					"hostname",
					"health"
				]
			}
		}
  }
}

You can apply the pattern to the response body and extract the following information:

• source: balancer
• event: health
• handler: webhook-custom

The values in the fields array represent the available template parameters you can use when constructing a payload.

• upstream_id
• ip
• port
• hostname
• health

These parameters can be used to issue notifications any time an upstream in your application is not reachable.

Available sources

• dao:crud: Handles dao:crud clustering events.
• balancer: Information from the load balancer like: upstream_id, ip, port, hostname, health
• ai-rate-limiting-advanced: Run an event when a rate limit has been exceeded.
• service-protection: Run an event when a rate limit has been exceeded.
• rate-limiting-advanced: Run an event when a rate limit has been exceeded.
• crud: Create, read, and update events from Kong Gateway entities such as Consumers.
• oas-validation: Runs an event when OAS validation Plugin fails.

For information about specific events related to a source, issue a GET request to the /event-hooks/sources/{source} endpoint. The API returns a list of all of the events associated to a source in the following format: balancer: health.

To create an Event Hook, call the Admin API’s /event-hooks endpoint.

curl -i -X POST http://localhost:8001/event-hooks/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "source": "crud",
      "event": "consumers",
      "handler": "webhook",
      "on_change": true,
      "config": {
        "url": "'$WEBHOOK_URL'"
      }
    }
    '