---
title: "Find or create a callback endpoint by URL"
method: POST
path: "/v1/endpoints/ensure"
---

# Find or create a callback endpoint by URL

`POST /v1/endpoints/ensure`

## Request

- Base URL: `https://docs.greatwait.dev` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.greatwait.dev/v1/endpoints/ensure`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer and API key in header `Greatwait-Environment` and API key in header `Greatwait-Project`

Finds or creates the callback endpoint at a URL in the caller's project and environment, without returning its signing secret. With no `name`, an existing endpoint that is not disabled at exactly this address is returned unchanged, preferring the one named after its URL; with a `name`, the endpoint must also carry that name. Otherwise one is created under the same rules as endpoints.create — HTTPS on effective port 443, no URL credentials or fragment, resolving only to public unicast addresses — and `created` is true. Optional `headers` apply only to an endpoint this call creates. Sent when the endpoint already exists, they are accepted if they are exactly its ordinary headers — what a retry of the creating call sends — and otherwise refused as `state_conflict` naming it; endpoints.update changes them. A secret value cannot be compared, so a call carrying one is refused for an endpoint that already exists. The result is metadata only: `signingSecret` says that the secret is not returned and where a signed-in member reveals it (`revealUrl`, the endpoint's dashboard page). Every callback is signed with that secret whether or not the receiver checks it. This is the endpoint operation agents use over MCP; endpoints.create, which returns the secret once, is withheld there.

## Request body

- object
  - `headers` union[]
    - union
      - object
        - `action` 'set', required
        - `name` string, required
        - `value` string, required
        - `secret` boolean
      - object
        - `action` 'keep', required
        - `name` string, required
      - object
        - `action` 'remove', required
        - `name` string, required
      - object
        - `action` 'suppress', required
        - `name` string, required
  - `name` string
  - `url` string, uri, required

## Response `200`

Find or create a callback endpoint by URL

- object
  - `headers` union[]
    - union
      - object
        - `name` string, required
        - `secret` false, required
        - `value` string, required
      - object
        - `name` string, required
        - `secret` true, required
        - `configured` true, required
      - object
        - `name` string, required
        - `suppressed` true, required
  - `createdAt` string, required
  - `disabledAt` string
  - `environmentKind` 'test' | 'live', required
  - `id` string, required
  - `name` string
  - `project` string, required
  - `signingKeys` object, required
    - `current` string, required
    - `next` object
      - `acknowledgedAt` string
      - `id` string, required
      - `overlapEndsAt` string, required
  - `status` 'active' | 'disabled', required
  - `updatedAt` string, required
  - `url` string, uri, required
  - `version` integer, required
  - `created` boolean, required
  - `signingSecret` object, required
    - `guidance` string, required
    - `returned` false, required
    - `revealUrl` string, uri

## Other responses

- `400`: Problem document. Possible codes at this status: invalid_request.
- `401`: Problem document. Possible codes at this status: authentication_required, credential_expired, credential_revoked.
- `403`: Problem document. Possible codes at this status: scope_missing.
- `409`: Problem document. Possible codes at this status: plan_limit_reached, project_archived, state_conflict.
- `429`: Problem document. Possible codes at this status: rate_limited.
- `503`: Problem document. Possible codes at this status: capability_not_configured, service_unavailable.

---

[API](https://skmtc.dev/greatwait/apis/greatwait-v1.md) · [All operations](https://skmtc.dev/greatwait/apis/greatwait-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/greatwait/apis/greatwait-v1/revisions/6855bce23e72?raw)