Webhook Commands
Register webhook callbacks for async notifications on long-running tasks.
Overview
Webhooks allow CCO to send HTTP POST notifications to your server when task events occur. This is useful for:
- Async notifications - Get notified when long-running tasks complete without polling
- CI/CD integration - Trigger downstream workflows when tasks finish
- Monitoring - Log events to external monitoring systems
- Blocker alerts - Receive immediate notification when blockers are detected
ℹ️
Webhooks are ideal for tasks that take longer than a few minutes. For quick tasks, consider using the synchronous return value instead.
cco webhook add
Register a webhook callback URL to receive task notifications.
| Parameter | Type | Description |
|---|---|---|
url |
positional | The webhook endpoint URL (required) |
--events |
option | Comma-separated list of events to subscribe to (default: "completion") |
Available Events
| Event | Description |
|---|---|
completion |
Fired when a task completes successfully |
blocker |
Fired when a blocker is detected during task execution |
error |
Fired when a task fails with an error |
Example
bash
cco webhook add https://my-server.com/webhook --events completion,blocker
cco webhook list
List all registered webhook endpoints and their subscribed events.
Example
bash
cco webhook list
cco webhook remove
Remove a registered webhook endpoint.
| Parameter | Type | Description |
|---|---|---|
url |
positional | The webhook endpoint URL to remove (required) |
Example
bash
cco webhook remove https://my-server.com/webhook
Payload Format
Webhook POST requests contain a JSON payload with the following structure:
json
{
"event": "completion",
"task_id": "abc123",
"repo": "/path/to/repo",
"status": "success",
"message": "Task completed successfully",
"timestamp": "2026-05-08T12:00:00Z"
}
⚠️
Your webhook endpoint must accept POST requests and return a 2xx status code within 10 seconds to be considered successful.