> ## 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.

# Webhooks

> Inbound webhook endpoint for triggering agent execution from external systems.

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](#monitoring-webhook-runs) or the `workspace` WebSocket channel to follow execution.

<Note>
  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).
</Note>

## 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.

<Warning>
  `X-Webhook-Secret` is deprecated (sunset 2026-12-31). Migrate to `X-Signature` before the sunset date.
</Warning>

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, keyed by the agent's webhook secret. |
| `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.

```json theme={null}
{
  "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

<Accordion title="Webhook execution pipeline">
  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
</Accordion>

### 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

<Note>
  If any prerequisite is missing the route is never registered, so the endpoint returns `404`.
</Note>

***

## 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
```

This endpoint requires internal token authentication (IPC only). The secret is stored as part of the agent configuration.

<Tip>
  You can also view the per-agent webhook secret in the Crewship UI under the agent's settings.
</Tip>