# Create a webhook endpoint

> The webhook_endpoints.create operation: POST /api/v1/webhook_endpoints in the REST API and the webhook_endpoints_create tool in the MCP server.

Creates an endpoint that receives the brand's events in the request's mode: Ownrecord POSTs each event it
subscribes to as JSON, signed with the `Ownrecord-Signature` header (see the webhooks concept page).

- `events` lists event types from the catalogue that are delivered to webhooks, or `["*"]` for all of them,
  including types added later.
- `url` must be a public `https` URL. In development and test (dev gate open), `http://localhost` works too.
- The response contains the signing secret in `secret`. **It is shown only once**: it is stored encrypted and
  can't be read again. Rotate it with `webhook_endpoints.rotate_secret` if you lose it.

A brand can have at most 16 endpoints per mode. Send a test event with `webhook_endpoints.test`.

## At a glance

- **REST:** `POST /api/v1/webhook_endpoints`
- **MCP tool:** `webhook_endpoints_create`
- **Operation ID:** `webhook_endpoints.create`
- **Scope:** Brand
- **Permission:** `webhooks:admin`
- **Risk tier:** `security`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` required
- **Modes:** Test and live
- **Authentication:** API key with the `webhooks:admin` scope
- **Since:** M4

## Request

### Body

A JSON object (`Content-Type: application/json`):

| Field         | Type            | Required | Description                                                                                 |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------- |
| `url`         | string          | Yes      | The https URL Ownrecord POSTs events to, e.g. <https://example.com/webhooks/ownrecord>.     |
| `events`      | array of string | Yes      | Event types to receive (from the event catalogue), or \["\*"] for every event of the brand. |
| `description` | string          | No       |                                                                                             |
| `enabled`     | boolean         | No       | Start receiving events at once (default) or create it disabled.                             |
| `metadata`    | object          | No       | Your own key-value pairs (at most 50 keys). On updates the whole set is replaced.           |

## Response

`201 Created` with a JSON object:

| Field                     | Type                               | Description |
| ------------------------- | ---------------------------------- | ----------- |
| `id`                      | `we_…` ID                          |             |
| `object`                  | `"webhook_endpoint"`               |             |
| `brandId`                 | `brd_…` ID                         |             |
| `livemode`                | boolean                            |             |
| `url`                     | string                             |             |
| `description`             | string or null                     |             |
| `events`                  | array of string                    |             |
| `enabled`                 | boolean                            |             |
| `disabledReason`          | one of `manual`, `failing` or null |             |
| `disabledAt`              | date-time or null                  |             |
| `failingSince`            | date-time or null                  |             |
| `secretRotatedAt`         | date-time or null                  |             |
| `previousSecretExpiresAt` | date-time or null                  |             |
| `metadata`                | object                             |             |
| `createdAt`               | date-time                          |             |
| `updatedAt`               | date-time                          |             |
| `secret`                  | string                             |             |

## Examples

### An endpoint for order fulfilment

```http
POST /api/v1/webhook_endpoints
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "url": "https://example.com/webhooks/ownrecord",
  "events": [
    "customer.created",
    "checkout.session.completed"
  ],
  "description": "Order fulfilment"
}
```

Response (`201`):

```json
{
  "id": "we_01m4tx5nj8emwbyf7y9vcf47z0",
  "object": "webhook_endpoint",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "url": "https://example.com/webhooks/ownrecord",
  "description": "Order fulfilment",
  "events": ["customer.created", "checkout.session.completed"],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "failingSince": null,
  "secretRotatedAt": null,
  "previousSecretExpiresAt": null,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z",
  "secret": "whsec_ExampleOnlyNotARealSigningSecret0000000"
}
```

### Every event of the brand

```http
POST /api/v1/webhook_endpoints
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "url": "https://example.com/webhooks/all",
  "events": [
    "*"
  ]
}
```

Response (`201`):

```json
{
  "id": "we_01m4tx5nj8emwbyf7y9vcf47z0",
  "object": "webhook_endpoint",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "url": "https://example.com/webhooks/all",
  "description": null,
  "events": ["*"],
  "enabled": true,
  "disabledReason": null,
  "disabledAt": null,
  "failingSince": null,
  "secretRotatedAt": null,
  "previousSecretExpiresAt": null,
  "metadata": {},
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z",
  "secret": "whsec_ExampleOnlyNotARealSigningSecret0000000"
}
```

## Errors

| Code                                                                                                             | HTTP status | When                                                                                       | What to do                                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)                           | 400         | A field is missing or malformed.                                                           | Fix the fields listed in `details.issues` and send the request again.                                                                                                        |
| [`webhook_url_not_allowed`](https://ownrecord.io/docs/reference/errors.md#webhook_url_not_allowed)               | 400         | The URL isn't https, or points at localhost, a private network or another refused address. | Use a public https URL without a user name, password or #fragment, e.g. <https://example.com/webhooks>. In development, <http://localhost> works while the dev gate is open. |
| [`webhook_event_type_invalid`](https://ownrecord.io/docs/reference/errors.md#webhook_event_type_invalid)         | 400         | An event type isn't in the catalogue or isn't delivered to brand webhook endpoints.        | List event types from the event catalogue that are delivered to webhooks (docs: reference → events), or "\*" for all of them.                                                |
| [`webhook_endpoint_limit_reached`](https://ownrecord.io/docs/reference/errors.md#webhook_endpoint_limit_reached) | 400         | The brand already has 16 endpoints in this mode.                                           | Delete an endpoint you no longer use, or subscribe an existing endpoint to more event types.                                                                                 |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)                           | 403         | You can't manage this brand's webhooks.                                                    | Ask an organization owner or admin for a role or scope that allows this action.                                                                                              |
| [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed)                     | 403         | You have no live-mode access, so you can't manage live webhooks.                           | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.                                                  |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).