packages/kilo-docs/pages/kiloclaw/triggers/webhooks.md
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.
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 %}
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}}
Once set up, the Webhook Integration card in Settings gives you several controls:
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.
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.
For additional security, you can require inbound requests to include a shared secret header. This is useful when the sending service supports webhook signing.
x-webhook-secret)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 %}
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.
application/jsonNow 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.