> For a complete page index of the Captain API documentation, fetch https://docs.captain.dev/llms.txt?excludeSpec=true

# Update Endpoint

PATCH https://api.filesearch.dev/v2/webhooks/endpoints/{endpoint_id}
Content-Type: application/json

Change an endpoint's URL, filters, description or `include_collection_name`, or pause and resume it with `disabled`. Only the fields sent change. Send an empty list to remove a filter.

Setting `disabled` to `false` also re-enables an endpoint that Captain disabled after sustained delivery failures. Events for jobs that finished while the endpoint was disabled are not sent automatically; use the recover endpoint for those.

Reference: https://docs.runcaptain.com/reference/webhooks/endpoints/update

## Request

### Path parameters

- `endpoint_id` (string, required) — The endpoint's id (`whe_...`).

### Body (application/json)

This endpoint expects a WebhookEndpointUpdate.

- `collection_ids` (list of string, optional, nullable) — Only jobs that index into these collections, by collection id (up to 10). Empty or omitted means every collection.
- `description` (string, optional, nullable) — Free-text label, up to 200 characters.
- `disabled` (boolean, optional, nullable) — `true` pauses deliveries, `false` resumes them. Setting `false` also re-enables an endpoint that was disabled after sustained delivery failures.
- `event_types` (list of string, optional, nullable) — Events to receive: any of `job.completed`, `job.completed_with_errors`, `job.failed`, `job.timed_out`, `job.cancelled`. Empty or omitted means all five.
- `include_collection_name` (boolean, optional, nullable) — Send `collection_name` in payloads. When any endpoint receiving an event turns this off, that event carries `collection_name: null`.
- `sources` (list of string, optional, nullable) — Only jobs from these sources: `api` (started by a call to an index endpoint) or `sync` (started by a storage sync). Empty or omitted means both.
- `sync_ids` (list of string, optional, nullable) — Only jobs started by these syncs (up to 10). Requires `sources` to include `sync` or be empty.
- `url` (string, optional, nullable) — HTTPS URL that receives events. Must start with `https://`, be reachable from the public internet, and be at most 2,048 characters.

## Response

### 200

Successful Response

- `endpoint_id` (string, required) — The endpoint's id (`whe_...`).
- `url` (string, required) — HTTPS URL that receives events.
- `description` (string, required) — Free-text label. Empty string when not set.
- `event_types` (list of string, required) — Events this endpoint receives. Empty means all five.
- `collection_ids` (list of string, required) — Collection filter. Empty means every collection.
- `sync_ids` (list of string, required) — Sync filter. Empty means no sync filter.
- `sources` (list of string, required) — Source filter (`api`, `sync`). Empty means both.
- `channels` (list of string, required) — Filters set in Captain Studio's Webhooks page that cannot be expressed as `collection_ids`, `sync_ids` and `sources`. Empty for endpoints whose filters were set through the API. Setting `collection_ids`, `sync_ids` or `sources` with `PATCH` replaces them.
- `include_collection_name` (boolean, required) — Whether payloads sent to this endpoint may carry `collection_name`.
- `disabled` (boolean, required) — `true` when no events are being sent to this endpoint.
- `disabled_reason` (string, required, nullable) — `delivery_failures` when Captain disabled the endpoint after sustained failed deliveries. `null` when it is enabled or was paused through the API.
- `last_delivery` (WebhookLastDelivery, required, nullable) — The most recent delivery, or `null` before the first one.
- `created_at` (string, required)
- `updated_at` (string, required)

## Errors

### 401 Unauthorized Error

Missing or invalid API key.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 403 Forbidden Error

The connection is read-only and cannot change webhooks (MCP connections without write access).

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 404 Not Found Error

`Webhook endpoint not found.` The id does not exist, or belongs to another organization.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 409 Conflict Error

Conflict with the endpoint's current state, or the organization already has 20 endpoints.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 422 Unprocessable Entity Error

A value was rejected. A route check returns `HTTP_ERROR` and names the value in `message`, for example `url must start with https://`. A malformed body returns `VALIDATION_ERROR` with one entry per field in `details`.

- `error` (string, required) — `HTTP_ERROR` when a route check rejected a value, `VALIDATION_ERROR` when the body is malformed.
- `message` (string, required) — What went wrong. For `HTTP_ERROR`, names the rejected value.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code. Present only on `HTTP_ERROR`.
- `details` (list of V2WebhooksEndpointsEndpointIdPatchResponsesContentApplicationJsonSchemaDetailsItems, optional) — Present only on `VALIDATION_ERROR`: one entry per invalid field, with `type`, `loc` and `msg`.

### 429 Too Many Requests Error

`Too many webhook management requests. Try again shortly.` Retry after the `Retry-After` header.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

### 503 Service Unavailable Error

Webhooks are temporarily unavailable. Retry shortly.

- `error` (string, required) — Error kind. `HTTP_ERROR` for errors raised by the route.
- `message` (string, required) — What went wrong.
- `path` (string, required) — The request path.
- `status_code` (integer, optional) — The HTTP status code.

## Types

### WebhookLastDelivery

- `at` (string, required) — When the most recent delivery attempt finished.
- `status` (enum, required) — Outcome of that delivery.
  - Allowed values: `succeeded`, `failed`

### V2WebhooksEndpointsEndpointIdPatchResponsesContentApplicationJsonSchemaDetailsItems

## Examples

**Request**

```json
{
  "collection_ids": [
    "2b8e6f10-3c4d-4e5f-8a9b-0c1d2e3f4a5b"
  ],
  "sources": [
    "sync"
  ]
}
```

**Response**

```json
{
  "endpoint_id": "whe_3f9a1c7e5b2d4a6c8e0f1a2b",
  "url": "https://example.com/webhooks/captain",
  "description": "Indexing notifications",
  "event_types": [
    "job.completed",
    "job.completed_with_errors",
    "job.failed"
  ],
  "collection_ids": [
    "2b8e6f10-3c4d-4e5f-8a9b-0c1d2e3f4a5b"
  ],
  "sync_ids": [],
  "sources": [
    "sync"
  ],
  "channels": [],
  "include_collection_name": true,
  "disabled": false,
  "disabled_reason": null,
  "last_delivery": {
    "at": "2026-09-23T10:05:13Z",
    "status": "succeeded"
  },
  "created_at": "2026-09-20T16:42:08Z",
  "updated_at": "2026-09-23T11:20:44Z"
}
```

**SDK Code**

```python Python
import requests

BASE_URL = "https://api.filesearch.dev"
API_KEY = "your_api_key"
ENDPOINT_ID = "whe_3f9a1c7e5b2d4a6c8e0f1a2b"

response = requests.patch(
    f"{BASE_URL}/v2/webhooks/endpoints/{ENDPOINT_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "collection_ids": [
            "2b8e6f10-3c4d-4e5f-8a9b-0c1d2e3f4a5b"
        ],
        "sources": [
            "sync"
        ]
    },
    timeout=30.0,
)
response.raise_for_status()
data = response.json()
print(f"Collections: {data['collection_ids']}, sources: {data['sources']}")

```

```typescript TypeScript
const BASE_URL = "https://api.filesearch.dev";
const API_KEY = "your_api_key";
const ENDPOINT_ID = "whe_3f9a1c7e5b2d4a6c8e0f1a2b";

const response = await fetch(`${BASE_URL}/v2/webhooks/endpoints/${ENDPOINT_ID}`, {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "collection_ids": [
      "2b8e6f10-3c4d-4e5f-8a9b-0c1d2e3f4a5b"
    ],
    "sources": [
      "sync"
    ]
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status} ${await response.text()}`);
const data = await response.json();
console.log(`Collections: ${data.collection_ids}, sources: ${data.sources}`);

```