<Intro>

<EndpointHeader />

<Description>

Registers a webhook endpoint that receives this workspace's events as signed HTTPS
`POST` requests. The endpoint starts `active` and receives only the event types listed
in `events`. Delivery, signing, and retry behavior are covered in the
[webhooks guide](/docs/guides/webhooks).

The `201` response is the only place the endpoint's signing secret (`whsec_` prefix)
ever appears: store it immediately. If you lose it, mint a new one with
[Rotate webhook signing secret](/docs/api/reference/rotate-webhook-secret). After
creating, [Send a test event](/docs/api/reference/test-webhook) to confirm your
receiver is reachable and verifies signatures correctly.

Invalid input (a non-HTTPS or non-public `url`, an event type outside the catalog)
returns a `422`, as does exceeding your organization's webhook endpoint limit
(`WebhookTooManyEndpoints`).

</Description>

</Intro>

<Payload kind="request">

<Field name="url" type="string" required>

<Description>

HTTPS URL to deliver events to, at most 2048 characters. The host must be publicly reachable: URLs on private, loopback, or link-local addresses are rejected with a `422`.

</Description>

</Field>

<Field name="events" type="array of string" required>

<Description>

Event types to subscribe to; the endpoint receives only matching events. Types outside the event catalog return a `422`, and an endpoint holds at most 100 entries. Platform types may be combined with `realtime.*` types on one endpoint, all signed with the endpoint's single secret. Server-enforced (returns `422` otherwise): a `realtime.*` type requires the `realtime` object, and `realtime` requires at least one `realtime.*` type.

</Description>

</Field>

<Field name="description" type="string">

<Description>

Human-readable label for this endpoint, up to 256 characters.

</Description>

</Field>

</Payload>

<Payload kind="response">

<Field name="id" type="string" required>

<Description>

Unique identifier for the endpoint (`whk_` prefix). Accepted as `webhook_id` by every `/v1/webhooks/{webhook_id}` operation.

</Description>

</Field>

<Field name="url" type="string" required>

<Description>

HTTPS URL Bird delivers this endpoint's events to.

</Description>

</Field>

<Field name="description" type="string">

<Description>

Human-readable label for the endpoint.

</Description>

</Field>

<Field name="events" type="array of string" required>

<Description>

Event types this endpoint is subscribed to; only matching events are delivered. Change the set with [Update a webhook endpoint](/docs/api/reference/update-webhook).

</Description>

</Field>

<Field name="status" type="string" required>

<Description>

Delivery state of the endpoint.

- `active`: the initial state; events are being delivered normally.
- `degraded`: recent deliveries are failing. Bird keeps delivering and retrying,
  and the endpoint returns to `active` automatically once deliveries succeed
  again.
- `paused`: all delivery is stopped, either because an update set `status` to
  `paused` or automatically after sustained delivery failures. A paused endpoint
  never resumes on its own: re-enable it with
  [Update a webhook endpoint](/docs/api/reference/update-webhook), then recover
  the missed events with
  [Replay missed events](/docs/api/reference/create-webhook-replay).

</Description>

<Description>

Possible values: `active`, `degraded`, `paused`

</Description>

</Field>

<Field name="created_at" type="string" required />

<Field name="updated_at" type="string" required />

<Field name="secret" type="string" required>

<Description>

Signing secret for this endpoint (`whsec_` prefix), used to verify the `webhook-signature` header on every delivery. Present in this response only: store it immediately, it cannot be retrieved again. If you lose it, mint a new one with [Rotate webhook signing secret](/docs/api/reference/rotate-webhook-secret).

</Description>

</Field>

</Payload>