Skip to main content
Crewship exposes a single inbound webhook that lets an external system (GitHub, Grafana, n8n, CI, …) trigger an agent run. The endpoint authenticates the request against the agent’s per-agent webhook secret, enqueues the run asynchronously, and returns 202 immediately. Use the monitoring endpoints or the workspace WebSocket channel to follow execution.
This endpoint uses webhook-secret authentication only — not session or CLI token auth. Provide exactly one of X-Signature (preferred) or X-Webhook-Secret (deprecated).

​
Trigger Agent via Webhook

POST /api/v1/webhooks/{crewId}/{agentId}/trigger
Triggers an agent run from an external system. The webhook validates the request against the agent’s per-agent webhook secret, then starts the agent asynchronously.

​
Authentication

The endpoint accepts two header-based schemes. Provide one of them; if both are absent the request is rejected with 401. X-Signature (preferred). A hex-encoded HMAC-SHA256 of the raw request body, keyed by the agent’s per-agent webhook secret (no sha256= prefix): 
X-Signature: <hex(HMAC-SHA256(body, secret))>
This binds the signature to the exact payload, so a leaked header from one request can’t be replayed against a different body. X-Webhook-Secret (deprecated). The per-agent secret sent in plaintext: 
X-Webhook-Secret: <per-agent-secret>
This path still works during the deprecation window but is going away. Requests authenticated this way receive Deprecation and Sunset: Thu, 31 Dec 2026 23:59:59 GMT response headers.
X-Webhook-Secret is deprecated (sunset 2026-12-31). Migrate to X-Signature before the sunset date.
Both schemes validate using constant-time comparison. This endpoint does not use session or CLI token authentication.

​
Path Parameters

ParameterTypeDescription
crewIdstringCrew ID the agent belongs to
agentIdstringAgent ID to trigger

​
Request Headers

HeaderRequiredDescription
Content-TypeYesapplication/json
X-SignatureOne ofPreferred. Hex HMAC-SHA256 of the raw body, keyed by the agent’s webhook secret.
X-Webhook-SecretOne ofDeprecated (sunset 2026-12-31). Per-agent webhook secret in plaintext.

​
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"
  }
}
The agent receives a formatted message: 
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 neither X-Signature nor X-Webhook-Secret is provided, or the supplied signature/secret is invalid.

​
What Happens Behind the Scenes

  1. Auth validation — the agent’s webhook secret is looked up via the internal IPC resolver; an X-Signature is verified as an HMAC of the body, otherwise a plaintext X-Webhook-Secret is compared (constant-time)
  2. Agent config resolution — the agent’s full configuration (CLI adapter, LLM model, credentials, etc.) is resolved
  3. Chat session creation — a webhook-scoped chat session is created or reused (webhook-{agentId})
  4. Container startup — the crew’s container runtime is ensured running
  5. Run record creation — a run record with trigger type WEBHOOK is created
  6. Agent execution — the agent is started asynchronously with a 10-minute timeout
  7. Log streaming — agent output is streamed to the log collector and broadcast via WebSocket on workspace:{workspaceId}
  8. 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 prerequisite is missing the route is never registered, so the endpoint returns 404.

​
Use Cases

SourceEventAgent Action
GitHub ActionsPR openedCode review agent analyzes changes
GrafanaAlert firedSRE agent investigates incident
n8n / ZapierForm submittedData processing agent
CI/CDBuild failedDebug agent analyzes logs
Cron / SchedulerTimed eventScheduled reporting agent
Custom serviceBusiness eventDomain-specific agent

​
Monitoring Webhook Runs

After triggering, use these endpoints to monitor execution:
EndpointDescription
GET /api/v1/agents/{agentId}/runsList execution history (filter by trigger type)
GET /api/v1/agents/{agentId}/logsGet 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
This endpoint requires internal token authentication (IPC only). The secret is stored as part of the agent configuration.
You can also view the per-agent webhook secret in the Crewship UI under the agent’s settings.