Webhooks - Crewship

Crewship exposes agent webhooks and pipeline-webhook triggers. Agent webhooks target one agent; pipeline webhooks target a saved routine. Both are asynchronous and return 202 after authentication and admission checks.

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. Replay protection (optional, recommended). Add an X-Timestamp header (unix seconds). When present, the signature must cover "{timestamp}.{body}" and the timestamp must be within 5 minutes of the server clock — a captured signed request replayed after that window is rejected with 400, and the timestamp itself can’t be swapped because it is part of the signed material:

X-Timestamp: 1751558400
X-Signature: <hex(HMAC-SHA256("1751558400." + body, secret))>

Requests without X-Timestamp keep the body-only scheme above (backward compatible). When a signature is present it is also used as the dedup identity (instead of any client-supplied Idempotency-Key), so a replay can’t force a second run by supplying a fresh key. Enforcing timestamps per agent. The timestamped scheme is optional by default so un-migrated senders don’t break — but a body-only signature stays replayable indefinitely (bounded only by the dedup window). Once an agent’s sender emits X-Timestamp, flip the agent to require it:

crewship agent update <agent> --webhook-require-timestamp
# turn it back off:
crewship agent update <agent> --webhook-require-timestamp=false

(API: PATCH /api/v1/agents/{id} with {"webhook_require_timestamp": true}; the current value is echoed on GET /api/v1/agents/{id} and in crewship agent get.) With it on, a body-only HMAC and the deprecated plaintext X-Webhook-Secret are both rejected with 400 pointing at the {timestamp}.{body} scheme — closing the replay window entirely for that agent. 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

Parameter	Type	Description
`crewId`	string	Crew ID the agent belongs to
`agentId`	string	Agent ID to trigger

Request Headers

Header	Required	Description
`Content-Type`	Yes	`application/json`
`X-Signature`	One of	Preferred. Hex HMAC-SHA256 of the raw body (or `"{timestamp}.{body}"` when `X-Timestamp` is set), keyed by the agent’s webhook secret.
`X-Timestamp`	Optional	Unix seconds. Enables replay protection: the signature must cover `"{timestamp}.{body}"` and the timestamp must be within 5 minutes of now.
`X-Webhook-Secret`	One of	Deprecated (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. 400 Bad Request if X-Timestamp is present but unparseable or outside the 5-minute tolerance (a stale or replayed signed request).

What Happens Behind the Scenes

Webhook execution pipeline

Auth validation — the agent’s webhook secret is read crew-scoped from the database (the plaintext secret never crosses an IPC hop); an X-Signature is verified as an HMAC of the body (or of "{timestamp}.{body}" when X-Timestamp is present, which must also be within the freshness window), otherwise a plaintext X-Webhook-Secret is compared (constant-time)
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
Ingress trust fence — the payload (event, source, data) is external, attacker-controlled input, so it is wrapped in a nonce-delimited <untrusted …> block and injection-scanned before it becomes the agent’s user message. The agent’s system prompt instructs it to treat fenced blocks as pure data, never as instructions. See Ingress trust fence.
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 prerequisite is missing the route is never registered, so the endpoint returns 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 webhook signing secret follows show-once semantics — the same convention as CLI tokens and notification-channel secrets. No API, CLI, or UI surface ever returns a stored secret back. To obtain one, rotate:

crewship agent rotate-webhook-secret <agent-slug>

or via the API:

POST /api/v1/agents/{agentId}/webhook-secret/rotate

or from the dashboard: Agent → Settings → Advanced → Webhook signing secret → Rotate. The UI confirms first (the previous secret stops validating the instant the new one is minted), then shows the value once with a copy button — it is never re-displayed on a reload. The response contains the freshly minted webhook_secret exactly once — store it in the external system (GitHub/Grafana/… webhook config) immediately. Deliveries signed with the previous secret are rejected as soon as the rotation lands. Rotation requires agent-edit rights (OWNER/ADMIN, or MANAGER for agents they created). GET /api/v1/agents/{agentId} exposes only a webhook_secret_set boolean so clients can tell whether a secret is configured.

The former internal endpoint GET /api/v1/internal/agents/{agentId}/webhook-secret was removed — the trigger endpoint validates signatures against the database directly, and the plaintext secret never crosses an IPC hop.

Pipeline webhooks

Pipeline-webhook administration is workspace-authenticated. Dispatch is public: the high-entropy token in the URL plus its HMAC signature are the credentials.

Method	Path	Auth	Description
GET	`/api/v1/workspaces/{workspaceId}/pipeline-webhooks`	member	List webhook metadata; never returns the signing secret
POST	`/api/v1/workspaces/{workspaceId}/pipeline-webhooks`	create	Create a webhook; returns the secret once
DELETE	`/api/v1/workspaces/{workspaceId}/pipeline-webhooks/{webhookId}`	delete	Soft-delete; returns `204`
POST	`/api/v1/webhooks/{token}`	token + HMAC	Fire the target routine asynchronously

Create accepts either target_pipeline_slug or target_pipeline_id:

{
  "name": "GitHub events",
  "target_pipeline_slug": "process-event",
  "target_pipeline_version": 3,
  "signing_secret": "optional-client-secret",
  "inputs_template": {"source": "github"},
  "enabled": true,
  "rate_limit_per_min": 120
}

name defaults to the target slug. If signing_secret is omitted, the server generates one. The 201 response includes signing_secret exactly once; list responses include signing_secret_set, not the secret. The response also contains token, target identifiers/version, inputs_template, enabled, rate-limit and last-fire telemetry. A zero or negative configured rate uses the server floor of 600 fires/minute. Creation requires encrypted credential storage; misconfiguration is 500. Invalid target/body is 400, and insufficient role is 403.

Pipeline dispatch

POST /api/v1/webhooks/{token}
Content-Type: application/json
X-Crewship-Signature: <hex HMAC-SHA256(body, signing_secret)>

The signature is required. With X-Crewship-Timestamp: <unix-seconds>, sign <timestamp>.<raw-body>; the timestamp must be fresh. The body may be any JSON (or raw bytes): the routine receives request-derived event, raw, and headers inputs. inputs_template may add keys but cannot override those three fields. Idempotency-Key (or X-Crewship-Event-ID) can select the deduplication identity; identical signed deliveries also deduplicate. Success returns:

{"run_id":"run_123","status":"PENDING","deduped":false}

A duplicate returns 202 with status: "DEDUPED", the original run_id, and deduped: true. The run may later be COMPLETED, FAILED, CANCELLED, or WAITING; poll /api/v1/workspaces/{workspaceId}/pipeline-runs/{runId}.

Status	Meaning
`400`	Body too large/unreadable
`401`	Missing or invalid HMAC/timestamp
`404`	Unknown, disabled, or deleted token (deliberately indistinguishable)
`409`	Target routine is not active, or its pinned version is unavailable
`429`	Per-token/concurrency limit; includes `Retry-After`
`503`	Dispatch dependencies are not wired

Dispatch does not accept session/JWT authentication, and it never falls back to an unsigned request.

​Trigger Agent via Webhook

​Authentication

​Path Parameters

​Request Headers

​Request Body

​Response

​What Happens Behind the Scenes

​Prerequisites

​Use Cases

​Monitoring Webhook Runs

​Getting the Webhook Secret

​Pipeline webhooks

​Pipeline dispatch

Trigger Agent via Webhook

Authentication

Path Parameters

Request Headers

Request Body

Response

What Happens Behind the Scenes

Prerequisites

Use Cases

Monitoring Webhook Runs

Getting the Webhook Secret

Pipeline webhooks

Pipeline dispatch