Skip to content

Commit 06ebb6f

Browse files
RomneyDaRomneyDa
committed
docs: webhooks docs
1 parent 6f992b7 commit 06ebb6f

File tree

2 files changed

+352
-1
lines changed

2 files changed

+352
-1
lines changed

‎docs/docs.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,8 @@
6161
"hub/agents/intro",
6262
"hub/agents/overview",
6363
"hub/agents/create-and-edit",
64-
"hub/agents/slack-agent"
64+
"hub/agents/slack-agent",
65+
"hub/agents/webhooks"
6566
]
6667
},
6768
"hub/sharing"

‎docs/hub/agents/webhooks.mdx‎

Lines changed: 350 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,350 @@
1+
---
2+
title: "Webhooks"
3+
description: "Kick off Cloud Agents from external events"
4+
---
5+
6+
# Webhook
7+
8+
## Overview
9+
10+
Webhooks allow you to trigger Background Agents automatically when external events occur. When a webhook receives data, it kicks off an agent session with the webhook payload appended to the prompt, executing your chosen agent in a specified repository.
11+
12+
## Quick Start
13+
14+
### 1. Create a Webhook
15+
16+
Navigate to **Settings → Webhooks** and click **Create Webhook**.
17+
18+
**SCREENSHOT - Settings webhooks page showing the "Create Webhook" button in the top-right corner**
19+
20+
### 2. Configure Your Webhook
21+
22+
Fill in the required fields:
23+
24+
- **Name**: A descriptive name for your webhook (e.g., "Zapier Bug Reports")
25+
- **Agent**: Select which agent to kick off when triggered
26+
- **Repository**: Choose the repository where the agent will run
27+
- **Advanced Settings (Optional)**:
28+
- **Secret Header Name**: Custom HTTP header for authentication (e.g., `X-Webhook-Secret`)
29+
- **Secret Value**: Secret token used to verify incoming request headers.
30+
31+
**SCREENSHOT - Create webhook dialog showing all fields including name, agent selector, repository dropdown, and collapsed advanced settings section**
32+
33+
### 3. Copy Your Webhook URL
34+
35+
After creating the webhook, copy the unique webhook URL from the webhooks table.
36+
37+
**SCREENSHOT - Webhooks table showing a webhook entry with the URL column highlighted and a copy button**
38+
39+
Format: `https://api.continue.dev/webhooks/ingest/{webhook-id}`
40+
41+
### 4. Use Your Webhook URL
42+
43+
Configure your external service (Zapier, Make, GitHub Actions, etc.) to POST data to this URL.
44+
45+
---
46+
47+
## Integration Examples
48+
49+
### Zapier
50+
51+
1. Create a new Zap with your desired trigger (e.g., "New Email in Gmail")
52+
2. Add a "Webhooks by Zapier" action
53+
3. Choose "POST" as the method
54+
4. Paste your webhook URL
55+
5. Configure the payload data (e.g., email subject, body, sender)
56+
6. (Optional) Add a custom header with your secret if configured
57+
58+
**SCREENSHOT - Zapier webhook configuration showing POST method, webhook URL field, and payload data configuration with example fields**
59+
60+
**Example payload sent to agent:**
61+
62+
```json
63+
{
64+
"subject": "Bug: Login button not working",
65+
"body": "Users are reporting that the login button...",
66+
"sender": "[email protected]",
67+
"priority": "high"
68+
}
69+
```
70+
71+
### GitHub Actions
72+
73+
Trigger agents from CI/CD pipelines:
74+
75+
```yaml
76+
name: Trigger Agent on Failed Test
77+
on:
78+
push:
79+
branches: [main]
80+
81+
jobs:
82+
notify-on-failure:
83+
runs-on: ubuntu-latest
84+
steps:
85+
- name: Run Tests
86+
id: tests
87+
run: npm test
88+
89+
- name: Trigger Webhook on Failure
90+
if: failure()
91+
run: |
92+
curl -X POST https://api.continue.dev/webhooks/ingest/YOUR-WEBHOOK-ID \
93+
-H "Content-Type: application/json" \
94+
-d '{
95+
"event": "test_failure",
96+
"branch": "${{ github.ref_name }}",
97+
"commit": "${{ github.sha }}",
98+
"workflow": "${{ github.workflow }}"
99+
}'
100+
```
101+
102+
### cURL (Manual Testing)
103+
104+
Test your webhook directly:
105+
106+
```bash
107+
curl -X POST https://api.continue.dev/webhooks/ingest/YOUR-WEBHOOK-ID \
108+
-H "Content-Type: application/json" \
109+
-d '{"test": "data", "message": "Hello from webhook"}'
110+
```
111+
112+
## How It Works
113+
114+
```
115+
┌─────────────────┐
116+
│ External Service│
117+
│ (Zapier, etc.) │
118+
└────────┬────────┘
119+
│ POST /webhooks/ingest/{id}
120+
│ + Payload Data
121+
▼
122+
┌─────────────────┐
123+
│ Continue API │ 1. Validate webhook
124+
│ │ 2. Check authentication
125+
└────────┬────────┘
126+
│
127+
▼
128+
┌─────────────────┐
129+
│ Agent Session │ 3. Spawn agent with:
130+
│ │ - Your chosen agent
131+
│ │ - Selected repository
132+
│ │ - Webhook payload appended to prompt
133+
└─────────────────┘
134+
```
135+
136+
### What Happens When Triggered
137+
138+
1. **Validation**: Continue validates the webhook exists and is enabled
139+
2. **Authentication**: If configured, verifies the secret header matches
140+
3. **Agent Creation**: Spawns a new agent session with:
141+
- The agent you selected
142+
- The repository you specified
143+
- The entire webhook payload (JSON) as the agent's prompt
144+
4. **Execution**: The agent processes the data and performs its configured tasks
145+
146+
---
147+
148+
## Managing Webhooks
149+
150+
### View All Webhooks
151+
152+
Navigate to **Settings → Webhooks** to see all configured webhooks.
153+
154+
**SCREENSHOT - Webhooks table showing multiple webhooks with columns: Name, Agent, Repository, URL, Status (enabled/disabled), Created date, and Actions**
155+
156+
### Enable/Disable Webhooks
157+
158+
Use the toggle switch to temporarily disable webhooks without deleting them.
159+
160+
**SCREENSHOT - Close-up of webhook table row with enabled toggle switch highlighted**
161+
162+
### Edit Webhooks
163+
164+
Click the edit button to modify webhook configuration. You can change:
165+
166+
- Name
167+
- Agent
168+
- Repository
169+
- Authentication settings (optional)
170+
171+
### Delete Webhooks
172+
173+
Click the delete button and confirm. This permanently removes the webhook and invalidates the URL.
174+
175+
---
176+
177+
## Troubleshooting
178+
179+
### Webhook Not Triggering
180+
181+
1. **Check webhook is enabled** - Look for the toggle in the webhooks table
182+
2. **Verify URL is correct** - Copy the URL directly from the table
183+
3. **Test with cURL** - Use the manual testing example above
184+
4. **Check authentication** - Ensure header name and value match exactly
185+
186+
### Authentication Failures
187+
188+
- Header names are case-insensitive but must match exactly
189+
- Secret values are case-sensitive
190+
- Both header name and value must be provided together
191+
- Re-save the webhook if you recently changed secrets
192+
193+
### Agent Not Running as Expected
194+
195+
- Verify the agent works when triggered manually
196+
- Check that the repository is accessible
197+
- Examine the agent session logs for errors
198+
- The webhook payload is passed as JSON to the agent's prompt
199+
200+
### Where to Find Logs
201+
202+
Agent sessions triggered by webhooks appear in **Agents → Sessions** with the name format:
203+
`Webhook: {webhook-name}`
204+
205+
**SCREENSHOT - Agent sessions list showing a session with name "Webhook: Zapier Bug Reports" and webhook source icon**
206+
207+
---
208+
209+
## Use Cases
210+
211+
### Bug Tracking Integration
212+
213+
Automatically investigate and create PRs for bugs reported via external systems.
214+
215+
### Customer Support
216+
217+
Trigger agents when support tickets are created to gather context and suggest solutions.
218+
219+
### Monitoring Alerts
220+
221+
Respond to production issues automatically when monitoring tools detect problems.
222+
223+
### Form Submissions
224+
225+
Process form data, validate inputs, and execute follow-up actions.
226+
227+
### Scheduled Tasks (via Zapier Schedule)
228+
229+
Run agents on a schedule by using Zapier's scheduler as the trigger.
230+
231+
### CI/CD Integration
232+
233+
Trigger agents on build failures, deployment events, or test results.
234+
235+
---
236+
237+
## Limits and Considerations
238+
239+
- Each webhook creates a new agent session
240+
- Agent sessions consume organization resources
241+
- Webhook URLs are unique and non-guessable UUIDs
242+
- Payloads are stored as part of the agent session
243+
- Maximum payload size: Follows standard HTTP request limits (~10MB)
244+
- Rate limiting may apply to prevent abuse
245+
246+
---
247+
248+
## API Reference
249+
250+
### Endpoint
251+
252+
```
253+
POST https://api.continue.dev/webhooks/ingest/{webhook-id}
254+
```
255+
256+
### Request Headers
257+
258+
| Header | Required | Description |
259+
| ---------------------- | ----------- | ---------------------------------------------- |
260+
| `Content-Type` | Yes | Must be `application/json` |
261+
| `{Your-Secret-Header}` | Conditional | Required if webhook has authentication enabled |
262+
263+
### Request Body
264+
265+
Any valid JSON payload. This will appended to the Agent's prompt.
266+
267+
### Response Codes
268+
269+
| Code | Description |
270+
| ---- | -------------------------------------- |
271+
| 200 | Success - Agent session created |
272+
| 401 | Authentication failed - Invalid secret |
273+
| 403 | Webhook is disabled |
274+
| 404 | Webhook not found |
275+
| 500 | Server error |
276+
277+
### Success Response
278+
279+
```json
280+
{
281+
"success": true,
282+
"agentSessionId": "uuid-of-created-session"
283+
}
284+
```
285+
286+
### Error Response
287+
288+
```json
289+
{
290+
"success": false,
291+
"error": "Error message description"
292+
}
293+
```
294+
295+
---
296+
297+
## Creating Agents for Webhooks
298+
299+
When a webhook triggers an agent, the incoming JSON payload is stringified and appended to your agent's prompt. Design your agent prompts to handle this structured data.
300+
301+
Agent files consist of YAML frontmatter and a markdown prompt. When triggered, the final prompt becomes:
302+
303+
```
304+
{agent prompt}
305+
306+
{stringified webhook payload}
307+
```
308+
309+
### Example: Bug Report Handler
310+
311+
Here's an agent designed to handle bug reports from webhooks:
312+
313+
```markdown
314+
---
315+
name: Bug Report Investigator
316+
tools: Read,Search,Bash,Fetch
317+
rules: continuedev/github-issue-creation-rules
318+
---
319+
320+
You are a bug investigation agent. When you receive a bug report:
321+
322+
1. Extract the bug details (title, description, priority, reporter)
323+
2. Search the codebase for related error messages or functions
324+
3. Document your findings and root cause analysis
325+
4. Create a detailed GitHub issue with your investigation
326+
327+
Expected webhook data:
328+
{
329+
"title": "Bug description",
330+
"description": "Details and reproduction steps",
331+
"priority": "high|medium|low",
332+
"reporter": "email or name"
333+
}
334+
335+
Here's the bug report data:
336+
```
337+
338+
The agent prompt should clearly describe the expected data structure and what actions to take. When Zapier or another service sends a webhook with bug details, the agent automatically investigates the issue and creates a GitHub issue with findings.
339+
340+
Create agents at https://hub.continue.dev/new?type=agents, then reference them by slug (e.g., `username/bug-investigator`) when setting up webhooks.
341+
342+
---
343+
344+
## Next Steps
345+
346+
- Create your first webhook in Settings → Webhooks
347+
- Design an agent to handle your webhook data
348+
- Test with cURL to verify it works
349+
- Connect to your favorite automation tool
350+
- Monitor agent sessions to see results

0 commit comments

Comments
 (0)