Documentation Index
Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
Use this file to discover all available pages before exploring further.
Trigger Agent via Webhook
POST /api/v1/webhooks/{crewId}/{agentId}/trigger
Authentication
Webhook authentication uses a per-agent HMAC secret. Include it in the X-Webhook-Secret header:
X-Webhook-Secret: <per-agent-secret>
Path Parameters
| Parameter | Type | Description |
|---|
crewId | string | Crew ID the agent belongs to |
agentId | string | Agent ID to trigger |
| Header | Required | Description |
|---|
Content-Type | Yes | application/json |
X-Webhook-Secret | Yes | Per-agent webhook secret |
Request Body
The payload is passed to the agent as context. The structure is flexible — include whatever data is relevant to the agent’s task.
{
"event": "pull_request.opened",
"source": "github",
"data": {
"repository": "org/repo",
"pr_number": 42,
"branch": "feat/new-feature",
"author": "developer",
"title": "Add user authentication",
"url": "https://github.com/org/repo/pull/42"
}
}
Webhook event received:
Event: pull_request.opened
Source: github
Data: {repository: org/repo, pr_number: 42, ...}
Response
The webhook returns immediately. Agent execution happens asynchronously.
202 Accepted on success — the body is {"status": "accepted"}. The status reflects the fire-and-forget contract: the agent run is enqueued asynchronously, and 202 (not 200) signals “we received it, work has not finished”.
401 Unauthorized if the webhook secret is invalid or missing.
What Happens Behind the Scenes
- Secret validation — the agent’s webhook secret is looked up via the internal IPC resolver and compared
- Agent config resolution — the agent’s full configuration (CLI adapter, LLM model, credentials, etc.) is resolved
- Chat session creation — a webhook-scoped chat session is created or reused (
webhook-{agentId})
- Container startup — the crew’s container runtime is ensured running
- Run record creation — a run record with trigger type
WEBHOOK is created
- Agent execution — the agent is started asynchronously with a 10-minute timeout
- Log streaming — agent output is streamed to the log collector and broadcast via WebSocket on
workspace:{workspaceId}
- Run completion — the run record is updated with status (
COMPLETED or FAILED), exit code, duration, and error message
Prerequisites
The webhook endpoint is only registered when all of the following are configured:
- Orchestrator is available
- Container provider (Keeper) is available
- Log writer is configured
- Internal token is set
If any of these are missing, the endpoint will return 404.
Use Cases
| Source | Event | Agent Action |
|---|
| GitHub Actions | PR opened | Code review agent analyzes changes |
| Grafana | Alert fired | SRE agent investigates incident |
| n8n / Zapier | Form submitted | Data processing agent |
| CI/CD | Build failed | Debug agent analyzes logs |
| Cron / Scheduler | Timed event | Scheduled reporting agent |
| Custom service | Business event | Domain-specific agent |
Monitoring Webhook Runs
After triggering, use these endpoints to monitor execution:
| Endpoint | Description |
|---|
GET /api/v1/agents/{agentId}/runs | List execution history (filter by trigger type) |
GET /api/v1/agents/{agentId}/logs | Get agent logs |
WebSocket workspace:{workspaceId} | Real-time agent.log events |
Getting the Webhook Secret
The per-agent webhook secret is available through the internal API:
GET /api/v1/internal/agents/{agentId}/webhook-secret
