event hooks docs

app/_data/entity_examples/upstream/example-upstream.yml

@@ -0,0 +1,5 @@
+name: my-upstream
+paths:
+  - /upstreams
+service: 
+  name: example-upstreams

app/_gateway_entities/event_hooks.md

@@ -0,0 +1,132 @@
+---
+title: Event hooks
+content_type: reference
+entities:
+  - event_hooks
+
+description: Event hooks allow Kong Gateway to communicate with target services or resources, notifying the target resource that an event was triggered. 
+related_resources:
+  - text: Services
+    url: /gateway/entities/service/
+  - text: Routing in {{site.base_gateway}}
+    url: /gateway/routing/
+
+tools:
+    - admin-api
+    - kic
+    - terraform
+schema:
+    api: gateway/admin-ee
+    path: /schemas/Event-hooks
+
+---
+
+
+## How do Event Hooks work?
+
+{{site.base_gateway}} Event Hooks work by configuring the following three elements: 
+
+* Sources: The actions or operation that trigger the event hook.
+* Events: The Kong 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.
+
+{% mermaid %}
+flowchart LR
+  E["Event Detected"]
+  F["Handler Activated"]
+  G["Action Executed"]
+  E --> F
+  F --> G
+
+{% endmermaid %}
+
+### Handlers
+
+There are four types of handlers that can be used with the Event Hooks entity: 
+
+* **`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.
+
+
+### Sources
+
+{{site.base_gateway}} offers the [`/event-hooks/sources`](/api/admin-ee/latest/#/Event-hooks/get-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 interepreted in the following pattern: 
+
+1. **Level 1**: The source, the action that triggers the event hook.
+2. **Level 2**: The event, this is the {{site.base_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: 
+
+
+```json
+{
+	"data": {
+		"balancer": {
+			"health": {
+				"fields": [
+					"upstream_id",
+					"ip",
+					"port",
+					"hostname",
+					"health"
+				]
+			}
+		}
+  }
+}
+```
+
+You can apply the pattern to the response body and extract the following information: 
+
+
+* **event**: `health`
+* **source**: `balancer`
+* **handler**: `webhook-custom`
+
+The values in the `fields` array represent the availble 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. 
+
+For step-by-step guides on configuring event hooks see the following docs: 
+
+* [How to configure a custom webhook](/how-to/create-a-custom-webhook)
+* [How to create a log event hook](/how-to/create-a-log-event-hook)
+* [How to create a lambda event hook](/how-to-create-a-lambda-event-hook)
+
+
+
+
+## Schema
+
+{% entity_schema %}
+
+
+
+## Configure an event hook
+
+
+    curl --request POST \
+      --url http://localhost:8001/event-hooks \
+      --header 'Content-Type: application/json' \
+      --header 'Kong-Admin-Token: kongAdminToken' \
+      --data '{
+      "source": "crud",
+      "event": "admins:create",
+      "handler": "webhook",
+      "config": {
+        "url": "http://<your host>/admin-1created"
+      }
+    }'

app/_how-tos/create-a-custom-webhook.md

@@ -0,0 +1,27 @@
+---
+title: Create a custom webhook to push information to Slack
+content_type: how_to
+
+related_resources:
+  - text: Event hooks
+    url: /gateway/entities/event_hooks
+
+works_on:
+    - on-prem
+
+tags:
+  - eventhooks
+  - webhook
+  - notifications
+tldr: 
+  q: How do I create a custom webhook using eventhooks
+  a: Send a `POST` request to the event_hooks endpoint containing the source, event, template and URL for your webhook. 
+
+prereqs:
+  entities:
+    upstream:
+        - example-upstream
+    routes:
+        - example-route
+---
+ssss

app/_how-tos/create-a-lambda-event-hook.md

@@ -0,0 +1,54 @@
+---
+title: Run custom code in a event hook
+content_type: how_to
+
+related_resources:
+  - text: Event hooks
+    url: /gateway/entities/event_hooks
+
+works_on:
+    - on-prem
+
+tags:
+  - eventhooks
+  - webhook
+  - notifications
+tldr: 
+  q: How do I write custom code in an event hook
+  a: Send a `POST` request to the event_hooks endpoint containing the source and event for the webhook.
+---
+
+## Create a lambda event hook
+
+1. Create a lua script to load into the lambda event hook. 
+
+    ```lua
+    return function (data, event, source, pid)
+    local user = data.entity.username
+    error("Event hook on consumer " .. user .. "")
+    end
+    ```
+2. Create a lambda event hook on the `consumers` event, with the `crud` source by creating a `POST` request to the Admin API. 
+
+    curl -i -X POST http://localhost:8001/event-hooks \
+        -d source=crud \
+        -d event=consumers:update \
+        -d handler=lambda \
+        -d on_change=true \
+        -d config.functions='return function (data, event, source, pid) local user = data.entity.username error("Event hook on consumer " .. user .. "") end'
+
+## Validate the webhook
+
+
+1. Using the Admin API create a new consumer: 
+
+    ```sh
+    curl -i -X POST http://localhost:8001/consumers \
+        -d username="my-consumer"
+    ```
+2. Review the logs at `/usr/local/kong/logs/error.log` for an an update about the creation of this consumer. The log will look similar to this: 
+
+    ```sh
+     2021/07/29 21:52:54 [error] 114#0: *153047 [kong] event_hooks.lua:190 [string "return function (data, event, source, pid)..."]:3: Event hook on consumer my-consumer, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001
+
+    ```

app/_how-tos/create-a-log-webhook.md

@@ -0,0 +1,46 @@
+---
+title: Create a log event hook to monitor consumer events
+content_type: how_to
+
+related_resources:
+  - text: Event hooks
+    url: /gateway/entities/event_hooks
+
+works_on:
+    - on-prem
+
+tags:
+  - eventhooks
+  - webhook
+  - notifications
+tldr: 
+  q: How do I create a log webhook to monitor consumer events
+  a: Send a `POST` request to the event_hooks endpoint containing the source and event for the webhook.
+---
+
+## Create the event hook
+
+Create a long event hook on the `consumers` event using the `crud` source. 
+
+```sh
+ curl -i -X POST http://{HOSTNAME}:8001/event-hooks \
+   -d source=crud \
+   -d event=consumers:update \
+   -d handler=log \
+   -d on_change=true
+```
+
+## Validate the webhook
+
+
+1. Using the Admin API create a new consumer: 
+
+    ```sh
+    curl -i -X POST http://localhost:8001/consumers \
+        -d username="my-consumer"
+    ```
+2. Review the logs at `/usr/local/kong/logs/error.log` for an an update about the creation of this consumer. The log will look similar to this: 
+
+    ```sh
+    192.168.65.1 - - [11/Dec/2024:23:20:56 +0000] "POST /consumers HTTP/1.1" 201 183 "-" "-"
+    ```

app/_how-tos/create-a-webhook.md

@@ -0,0 +1,78 @@
+---
+title: Create a webhook that monitors Consumer creation
+content_type: how_to
+
+related_resources:
+  - text: Event hooks
+    url: /gateway/entities/event_hooks
+
+works_on:
+    - on-prem
+
+tags:
+  - eventhooks
+  - webhook
+  - notifications
+tldr: 
+  q: How do I create a webhook that monitors for the creation of new consumers?
+  a: Send a `POST` request to the event_hooks endpoint containing the source, event, template and URL for your webhook. 
+
+prereqs:
+  inline:
+    - title: A webhook URL
+      content: |
+        * You can gnerate a URL by navigating to https://webhook.site and copying the free URL.
+---
+
+
+## Create a webhook
+
+1. Using the Admin API, create an event hook on the consumers event by issuing a `POST` request to the `/event-hooks` endpoint.
+
+        curl -i -X POST http://localhost:8001/event-hooks \
+            -d source=crud \
+            -d event=consumers:update \
+            -d handler=webhook \
+            -d on_change=true \
+            -d config.url=https://webhook.site/94688621-990a-407f-b0b2-f92322d04c700"
+
+2. Issuing this `POST` request will send a request of type `ping` to the webhook URL verifying that the webhook is configured correctly.
+
+
+
+## Validate the webhook
+
+
+1. Using the Admin API create a new consumer: 
+
+    ```sh
+    curl -i -X POST http://localhost:8001/consumers \
+        -d username="my-consumer"
+    ```
+2. Verify on webhook.site that you received a `POST` request. It will look like this: 
+
+    ```json
+    {
+    "event_hooks": {
+        "id": "88a0d071-29c8-4d6a-827e-dbecf09e917c",
+        "event": "consumers:update",
+        "updated_at": 1733955343,
+        "config": {
+        "headers": {
+            "content-type": "application/json"
+        },
+        "ssl_verify": false,
+        "url": "https://webhook.site/94688621-990a-407f-b0b2-123923ad04c700"
+        },
+        "source": "crud",
+        "created_at": 1733955343,
+        "handler": "webhook",
+        "on_change": true
+    },
+    "operation": "create",
+    "source": "kong:event_hooks",
+    "event": "ping"
+    }
+    ```
+
+This response body contains the `operation`, the `source`, and the `event`, confirming that a new user was created 

app/_landing_pages/gateway/entities.yaml

@@ -52,3 +52,7 @@ rows:
       - type: entity_card
         config:
           entity: workspace
+    - blocks: 
+      - type: entity_card
+        config:
+          entity: event_hooks