# Create a webhook subscription.

`POST /webhooks`

> Wheelhouse Revenue Management API. Web version: https://docs.usewheelhouse.com/rm/reference/rm-create-webhook · OpenAPI spec: https://docs.usewheelhouse.com/rm/openapi.yaml · Operation ID: `rmCreateWebhook` · Tag: Webhooks

Registers an HTTPS endpoint to receive the given event types. The subscription covers the authenticated user's entire portfolio — owned listings plus listings shared with them to manage — and each delivery names only listings they can access.

The response is the **only** place the signing secret appears; store it, because it cannot be read back afterwards. If you lose it, use `POST /webhooks/{id}/rotate_secret`.

The endpoint must be `https`. Deliveries begin with the next batch window.

## Request

`POST https://api.usewheelhouse.com/ss_api/v1/webhooks`

Authentication: send your RM API key in the `X-Integration-Api-Key` header (see https://docs.usewheelhouse.com/rm/authentication.md). Modifies data; read-only keys get `403 Forbidden`.

### Request body (`application/json`, required)

- `url` (string, required, example: `https://example.com/wheelhouse/webhooks`): HTTPS endpoint that deliveries are posted to.
- `event_types` (array of string, required, each item one of: `recommendations.updated`, `reservations.ingested`, `flags.detected`): Event types this subscription should receive. See `GET /webhook_events`.
- `description` (string): Label for this subscription.

### Example request

```bash
curl -X POST 'https://api.usewheelhouse.com/ss_api/v1/webhooks' \
  -H 'X-Integration-Api-Key: <your RM API key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://example.com/wheelhouse/webhooks",
  "event_types": [
    "recommendations.updated"
  ]
}'
```

Only required parameters and body fields are filled in, with placeholder values. Add the optional ones you need from the lists above; some are required in combination, as their descriptions say.

## Responses

### 201

The created subscription, including its signing secret.

Body (`application/json`): object `webhook_with_secret`

A registered webhook subscription.

A subscription including its signing secret. Returned only on creation and by
`POST /webhooks/{id}/rotate_secret`; store it, because it cannot be read back.

- `id` (integer, required): The Wheelhouse internal subscription ID.
- `url` (string, required, example: `https://example.com/wheelhouse/webhooks`): The HTTPS endpoint deliveries are posted to.
- `description` (string, nullable): Label for this subscription.
- `event_types` (array of string, required): The event types this subscription receives.
- `enabled` (boolean, required): Whether deliveries are being sent. Set to `false` automatically after sustained
  delivery failures; re-enable with `PUT /webhooks/{id}`.
- `consecutive_failures` (integer): Failed deliveries since the last successful one. Reset on success.
- `disabled_at` (string (date-time), nullable): When the subscription was disabled, automatically or otherwise (ISO-8601).
- `last_delivered_at` (string (date-time), nullable): When a delivery to this endpoint last succeeded (ISO-8601).
- `created_at` (string (date-time)): When the subscription was created (ISO-8601).
- `secret` (string, required, example: `whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0`): Secret used to verify the `Wh-Signature` header on each delivery. Recompute
  `HMAC-SHA256(secret, "<t>.<raw body>")` and compare.

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "id": 0,
  "url": "https://example.com/wheelhouse/webhooks",
  "description": "string",
  "event_types": [
    "string"
  ],
  "enabled": true,
  "consecutive_failures": 0,
  "disabled_at": "2026-01-01T00:00:00Z",
  "last_delivered_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "secret": "whsec_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0"
}
```

### 400

An unknown event type was provided, or a required field was missing.

### 401

API key authorization failed.

### 403

The API key is read-only and may not be used to create a webhook.

### 409

A concurrent webhook request for this user is already in progress. Retry once it completes.

### 422

The endpoint was rejected. It must be an `https` URL on port 443 that
resolves to a publicly routable address. This is re-checked before every
delivery, so an endpoint that stops meeting it also stops receiving events.

### 429

Rate limit exceeded — the API key has sent too many requests. Wait before retrying. See the **Rate Limits** section in the overview for the recommended exponential backoff strategy.

Body (`application/json`): object

- `error` (string, example: `API token is at rate limit`)

Example shape (generated from the schema; placeholder values, not a real response):

```json
{
  "error": "API token is at rate limit"
}
```
