Event Hooks is a new Kong Enterprise feature launched in the Kong Gateway 2.5 Release. This feature sends you notifications when certain events happen on your Kong Gateway deployment. Kong Gateway listens for events, like routes, services, consumers, certificates, plugins, workspaces and RBAC roles created, updated or removed. 

You can also create or extend Kong Plugins and add the Event Hooks functionality for custom use cases. Businesses can use Event Hooks to bring enhanced awareness of change in a fully automated fashion, which ultimately increases enterprise visibility and reduces risk.

Event Hooks Use Case

A customer is utilizing Kong Workspaces to provide a logical separation between the management and configuration of their APIs with various teams. Each team uses a different logging tool or endpoint. By configuring the HTTP Log plugin with different logging endpoints for each Workspace, each team’s API traffic is logged to separate logging endpoints. But what if a customer wants a global view of all API traffic without configuring another plugin?

By adding Event Hooks to the HTTP Log plugin, we can easily solve this problem, with the added benefit of not affecting existing functionality. 

With just a few lines of code, it is possible to extend the HTTP Log plugin to provide the functionality required.

Kong Plugin Development Refresher

A Kong plugin allows you to inject custom logic in Lua, Go or JavaScript at several entry points in the lifecycle of a request and response or a TCP stream connection as it is proxied by Kong. 

Plugins consist of Lua modules interacting with the request and response objects or streams via the Plugin Development Kit (or “PDK”) to implement arbitrary logic. The Lua-based Plugin Development Kit (or “PDK”) is a set of Lua functions and variables that plugins can use to implement their own logic. Refer to the Kong Plugin Development Guide for more information. Or follow along in our Lua and JavaScript tutorials.

Implementing Event Hooks

A plugin consists of two mandatory modules:

http-log-plugin

├── handler.lua

└── schema.lua

• handler.lua: This is the core of your plugin. It’s an interface to implement, in which each function runs at the desired moment in a request’s lifecycle.
• schema.lua: Your plugin probably has to retain some configuration entered by the user. This module holds the schema of that configuration and defines rules on it so that the user can only enter valid configuration values.

Since we are extending an existing plugin, we can simply add the Event Hook functionality and reuse functionality from the HTTP Log plugin.

To enable Event Hooks in the plugin, all that is required are three lines of code as follows:

1. First, load the Event Hooks library using require “kong.enterprise_edition.event_hooks” 
2. In the :init_worker() phase of a plugin lifecycle, this is executed upon every Nginx worker process’ startup. Here we register the event hook for our plugin using the event_hooks.publish()  function.
3. Next, in the :log() phase we add the event_hooks.emit()  function. This fires an asynchronous request to an endpoint.

Below is the complete source code for handler.lua:

local event_hooks  = require "kong.enterprise_edition.event_hooks"
local HttpLogHandler = require "kong.plugins.http-log.handler"

local HttpLogHandlerEnterprise = {
 PRIORITY = 12,
 VERSION = "0.1.0",
}

function HttpLogHandlerEnterprise:init_worker()

 -- register event hook
 event_hooks.publish("http-log-enterprise", "log", {
   fields = { "consumer", "ip", "service", "route" },
   unique = { "consumer", "ip", "service" },
   description = "Run an event for a request",
 })

end

function HttpLogHandlerEnterprise:log(conf)

 -- execute event hook
 event_hooks.emit("http-log-enterprise", "log", {
   consumer = kong.client.get_consumer() or {},
   ip = kong.client.get_forwarded_ip(),
   service = kong.router.get_service() or {},
   route = kong.router.get_route() or {},
 })

 -- execute HTTP Log core functionality
 HttpLogHandler:log(conf)

end

return HttpLogHandlerEnterprise

And for schema.lua, we load the existing HTTP Log schema.lua library:

local HttpLogSchema = require "kong.plugins.http-log.schema"
HttpLogSchema.name = "http-log-enterprise"

return HttpLogSchema

Configuring the HTTP Log Event Listener

Once we have deployed the enhanced HTTP Log plugin, use the Kong Admin API to retrieve the Event Hook HTTP Log source. I recommend using a tool such as Insomnia, which is a lightweight RESTFul client. Using the /event-hooks/sources endpoint returns a lot of data, but using Insomnia allows you to collapse fields you are not interested in.

The new HTTP Log plugin is returned in the list of Event Hook sources. Next, configure the HTTP Log Event Hook.

Here, we are configuring a webhook handler. This makes a JSON POST request to a provided URL with the event data as payload. In our case, by configuring the Event Hook functionality in the HTTP Plugin, we configure a URL webhook endpoint used by all HTTP Log instances. This means we can use the Event Hook Webhook feature to log all API traffic across a Kong Deployment using the Event Hooks feature. Still, each Team associated with a Kong Workspace can also continue to use their own logging instances or endpoints.

Conclusion

By either reusing the built-in Event Hooks sources or adding to the Event Hook sources by extending or creating new plugins, Event Hooks greatly extends Kong’s observability options.