mirror of
https://github.com/Kilo-Org/kilocode.git
synced 2026-09-24 16:02:55 +08:00
Merge pull request #8091 from Kilo-Org/docs/kiloclaw-webhooks
docs(kiloclaw): add Triggers section with webhooks documentation
This commit is contained in:
Andrew Storms
@@ -37,6 +37,14 @@ export const KiloClawNav: NavSection[] = [
|
||||
{ href: "/kiloclaw/development-tools/google", children: "Google Workspace" },
|
||||
],
|
||||
},
|
||||
{
|
||||
href: "/kiloclaw/triggers",
|
||||
children: "Triggers",
|
||||
subLinks: [
|
||||
{ href: "/kiloclaw/triggers", children: "Overview" },
|
||||
{ href: "/kiloclaw/triggers/webhooks", children: "Webhooks" },
|
||||
],
|
||||
},
|
||||
{
|
||||
href: "/kiloclaw/tools",
|
||||
children: "Tools",
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: "Triggers"
|
||||
description: "Automate your KiloClaw agent with webhooks and scheduled triggers"
|
||||
---
|
||||
|
||||
# Triggers
|
||||
|
||||
Triggers let external events and schedules drive your KiloClaw agent automatically. Instead of typing every instruction yourself, triggers deliver messages to your agent on your behalf. This lets it react to real-world events or run tasks on a schedule without polling.
|
||||
|
||||
All triggers are managed from the **Settings** tab on your [KiloClaw dashboard](/docs/kiloclaw/dashboard).
|
||||
|
||||
## Trigger Types
|
||||
|
||||
| Type | Description | Status |
|
||||
| --- | --- | --- |
|
||||
| [**Webhooks**](/docs/kiloclaw/triggers/webhooks) | Receive HTTP requests from external services (GitHub, Stripe, monitoring tools, etc.) and deliver them as chat messages to your agent | Available |
|
||||
| **Time-based** | Run tasks on a schedule using cron expressions | Coming soon |
|
||||
|
||||
## How Triggers Work
|
||||
|
||||
1. An event occurs (an HTTP request arrives, or a schedule fires)
|
||||
2. The trigger validates the request and renders the payload through a **prompt template**
|
||||
3. The rendered message is delivered to your KiloClaw instance as a chat message
|
||||
4. Your agent processes and responds like any other conversation
|
||||
|
||||
Prompt templates give you control over how payloads are presented to your agent. You can include instructions, context, and formatting alongside the raw event data.
|
||||
|
||||
## Related
|
||||
|
||||
- [Webhooks](/docs/kiloclaw/triggers/webhooks)
|
||||
- [KiloClaw Overview](/docs/kiloclaw/overview)
|
||||
- [Dashboard Reference](/docs/kiloclaw/dashboard)
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: "Webhooks"
|
||||
description: "Trigger your KiloClaw agent from external events using webhooks"
|
||||
---
|
||||
|
||||
# Webhooks
|
||||
|
||||
KiloClaw supports inbound webhooks so external events can trigger your agent automatically. Form submissions, alerts, calendar updates, ecommerce orders, IoT sensor data; anything that can send an HTTP request can kick off a conversation with your agent. When a webhook fires, the payload is rendered through a prompt template and delivered as a chat message to your KiloClaw instance. The agent processes and responds as if you typed it yourself.
|
||||
|
||||
## Setup
|
||||
|
||||
1. Go to the **Settings** tab on your [KiloClaw dashboard](/docs/kiloclaw/dashboard)
|
||||
2. Find the **Webhook Integration** card and click **Manage**
|
||||
3. Click **Set Up Webhook**
|
||||
|
||||
KiloClaw generates a unique webhook URL for your instance. Copy it and configure it as the destination in whatever service you want to receive events from (GitHub, Stripe, a monitoring tool, etc.).
|
||||
|
||||
{% callout type="warning" title="Treat the URL as a secret" %}
|
||||
The webhook URL contains 128 bits of entropy and acts as its own credential (similar to Slack webhook URLs). Anyone with the URL can send messages to your instance. Do not commit it to public repositories or share it in public channels.
|
||||
{% /callout %}
|
||||
|
||||
## How It Works
|
||||
|
||||
1. An external service sends an HTTP POST to your webhook URL
|
||||
2. The webhook worker validates the request (and optionally checks authentication)
|
||||
3. The payload is rendered through your **prompt template** (see below)
|
||||
4. The rendered message is delivered to your KiloClaw instance as a chat message
|
||||
5. Your agent receives and responds to the message like any other conversation
|
||||
|
||||
## Prompt Template
|
||||
|
||||
The prompt template controls how webhook payloads are presented to your agent. You can customize it from the **Webhook Integration** section in Settings.
|
||||
|
||||
**Default template:**
|
||||
|
||||
```
|
||||
You received a webhook event. Here is the payload:
|
||||
|
||||
{{bodyJson}}
|
||||
```
|
||||
|
||||
**Available variables:**
|
||||
|
||||
| Variable | Description |
|
||||
| --- | --- |
|
||||
| `{{body}}` | Raw request body |
|
||||
| `{{bodyJson}}` | Pretty-printed JSON body |
|
||||
| `{{method}}` | HTTP method (e.g., `POST`) |
|
||||
| `{{headers}}` | Request headers |
|
||||
| `{{path}}` | Request path |
|
||||
| `{{query}}` | Query string parameters |
|
||||
| `{{timestamp}}` | Time the webhook was received |
|
||||
|
||||
You can tailor the template to give your agent more context. For example:
|
||||
|
||||
```
|
||||
A GitHub push event just arrived. Summarize the changes and open a PR if any tests are affected.
|
||||
|
||||
Payload:
|
||||
{{bodyJson}}
|
||||
```
|
||||
|
||||
## Managing Your Webhook
|
||||
|
||||
Once set up, the Webhook Integration card in Settings gives you several controls:
|
||||
|
||||
### Pause and Resume
|
||||
|
||||
Toggle the **Active/Paused** switch to temporarily stop accepting webhooks without deleting the URL. When paused, incoming requests are rejected. Resume at any time to start accepting them again.
|
||||
|
||||
### Rotate URL
|
||||
|
||||
If your webhook URL is compromised, click **Rotate URL** to generate a new one. This immediately invalidates the old URL, so you will need to update your integrations with the new URL afterward. A confirmation dialog is shown before rotation.
|
||||
|
||||
### Webhook Authentication (Optional)
|
||||
|
||||
For additional security, you can require inbound requests to include a shared secret header. This is useful when the sending service supports webhook signing.
|
||||
|
||||
1. Toggle **Webhook Authentication** to enabled
|
||||
2. Set the **Secret Header** name (default: `x-webhook-secret`)
|
||||
3. Enter a **Shared Secret** value
|
||||
4. Click **Save**
|
||||
|
||||
Requests missing the header or providing an incorrect secret are rejected.
|
||||
|
||||
{% callout type="note" title="Authentication is optional" %}
|
||||
The webhook URL itself is already a credential (128-bit entropy). Authentication adds a second layer and is only needed if your sending service requires or supports it.
|
||||
{% /callout %}
|
||||
|
||||
## Viewing Webhook Activity
|
||||
|
||||
KiloClaw webhooks also appear in the **Webhooks** page under Cloud (read only). From there you can click **View Captured Requests** to inspect recent payloads, response codes, and timing. This is useful for debugging integration issues.
|
||||
|
||||
## Example: GitHub Push Notifications
|
||||
|
||||
1. Set up a webhook in your KiloClaw Settings
|
||||
2. In your GitHub repository, go to **Settings > Webhooks > Add webhook**
|
||||
3. Paste your KiloClaw webhook URL as the **Payload URL**
|
||||
4. Set **Content type** to `application/json`
|
||||
5. Select the events you want to trigger on (e.g., **Just the push event**)
|
||||
6. Click **Add webhook**
|
||||
|
||||
Now every push to that repository sends a payload to your agent. Customize the prompt template to tell the agent what to do with it. You could have it summarize commits, run checks, notify a channel, or anything else.
|
||||
|
||||
## Related
|
||||
|
||||
- [KiloClaw Overview](/docs/kiloclaw/overview)
|
||||
- [Dashboard Reference](/docs/kiloclaw/dashboard)
|
||||
- [GitHub Integration](/docs/kiloclaw/development-tools/github)
|
||||
- [Connecting Chat Platforms](/docs/kiloclaw/chat-platforms)
|
||||
Reference in New Issue
Block a user