Create Endpoint | Captain Docs

import os
import requests
BASE_URL = "https://api.captain.dev"
API_KEY = "your_api_key"
SECRET_FILE = "captain-webhook.env"
def save_webhook_secret(secret):
    """Write the secret to an env file only this user can read. The receiver loads it as CAPTAIN_WEBHOOK_SECRET."""
    fd = os.open(SECRET_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
    os.fchmod(fd, 0o600)  # also tightens a file that already existed
    with os.fdopen(fd, "w") as secret_file:
        secret_file.write(f"CAPTAIN_WEBHOOK_SECRET={secret}\n")
response = requests.post(
    f"{BASE_URL}/v2/webhooks/endpoints",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "url": "https://example.com/webhooks/captain",
        "description": "Indexing notifications",
        "event_types": [
            "job.completed",
            "job.completed_with_errors",
            "job.failed"
        ]
    },
    timeout=30.0,
)
response.raise_for_status()
data = response.json()
print(f"Endpoint: {data['endpoint_id']}")
save_webhook_secret(data["secret"])
print(f"Saved the signing secret to {SECRET_FILE}")

{
  "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": [],
  "sync_ids": [],
  "sources": [],
  "channels": [],
  "include_collection_name": true,
  "disabled": false,
  "disabled_reason": null,
  "last_delivery": null,
  "created_at": "2026-09-20T16:42:08Z",
  "updated_at": "2026-09-20T16:42:08Z",
  "secret": "whsec_kR2v9XoJ4mQ8sT1wY6zB3nC7fH0dL5gP2aE9uI4xV8c="
}

Register an HTTPS URL that receives a signed request when any indexing job in the organization finishes, in any environment. The payload’s data.environment field says where the job ran.

The response includes secret, the signing secret the receiver uses to verify requests. It is returned only in this response and cannot be read back, so store it right away. If it is lost, rotate it.

Endpoints belong to the organization, and an API key from any of its environments sees and manages the same endpoints. An organization can have up to 20 endpoints. Filters combine with AND across collection_ids, sync_ids and sources, and OR within each list; the product of the non-empty list sizes must be at most 10. See the Webhooks guide.

Register an HTTPS URL that receives a signed request when any indexing job in the organization finishes, in any environment. The payload's `data.environment` field says where the job ran. The response includes `secret`, the signing secret the receiver uses to verify requests. It is returned only in this response and cannot be read back, so store it right away. If it is lost, rotate it. Endpoints belong to the organization, and an API key from any of its environments sees and manages the same endpoints. An organization can have up to 20 endpoints. Filters combine with AND across `collection_ids`, `sync_ids` and `sources`, and OR within each list; the product of the non-empty list sizes must be at most 10. See the [Webhooks](/guides/webhooks) guide.

Request

This endpoint expects an object.

urlstringRequired

HTTPS URL that receives events. Must start with https://, be reachable from the public internet, and be at most 2,048 characters.

collection_idslist of strings or nullOptional

Only jobs that index into these collections, by collection id (up to 10). Empty or omitted means every collection.

descriptionstring or nullOptional

Free-text label, up to 200 characters.

disabledbooleanOptionalDefaults to false

Create the endpoint without sending to it yet. Defaults to false.

event_typeslist of strings or nullOptional

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_namebooleanOptionalDefaults to true

Send collection_name in payloads. When any endpoint receiving an event turns this off, that event carries collection_name: null.

sourceslist of strings or nullOptional

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_idslist of strings or nullOptional

Only jobs started by these syncs (up to 10). Requires sources to include sync or be empty.

Response

Successful Response

endpoint_idstring

The endpoint’s id (whe_...).

urlstring

HTTPS URL that receives events.

descriptionstring

Free-text label. Empty string when not set.

event_typeslist of strings

Events this endpoint receives. Empty means all five.

collection_idslist of strings

Collection filter. Empty means every collection.

sync_idslist of strings

Sync filter. Empty means no sync filter.

sourceslist of strings

Source filter (api, sync). Empty means both.

channelslist of strings

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_nameboolean

Whether payloads sent to this endpoint may carry collection_name.

disabledboolean

true when no events are being sent to this endpoint.

disabled_reasonstring or null

delivery_failures when Captain disabled the endpoint after sustained failed deliveries. null when it is enabled or was paused through the API.

last_deliveryobject or null

The most recent delivery, or null before the first one.

created_atstringformat: "date-time"

updated_atstringformat: "date-time"

secretstring

The signing secret (whsec_...). Returned only in this response.

Errors

401

Unauthorized Error

403

Forbidden Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

503

Service Unavailable Error

Register an HTTPS URL that receives a signed request when any indexing job in the organization finishes, in any environment. The payload’s data.environment field says where the job ran.