> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fire.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# Create webhook

> Registers a new webhook endpoint. The response includes the signing secret — store it securely, it is shown only once.

<ParamField header="x-api-key" type="string" required>
  BOH API key with `admin:webhooks` scope.
</ParamField>

<ParamField body="url" type="string" required>
  HTTPS URL that will receive POST requests. Must start with `https://`.
</ParamField>

<ParamField body="events" type="string[]" required>
  One or more event types to subscribe to. Supported events:

  * `inventory_transaction.completed`
  * `inventory_transaction.failed`
  * `purchase_order.status_changed`
  * `api_key.expiring`
  * `ping`
</ParamField>

<ResponseField name="endpoint" type="object">
  The created endpoint: `id`, `url`, `events`, `is_active`, `disabled_reason`, `consecutive_failures`, `created_at`, `updated_at`.
</ResponseField>

<ResponseField name="secret" type="string">
  Signing secret (`whsec_...`). **Shown only once.** Store it in your secrets manager immediately. Use it to verify the `X-BOH-Signature` header on incoming requests.
</ResponseField>

<RequestExample>
  ```json theme={null}
  {
    "url": "https://yourapp.com/webhooks/boh",
    "events": [
      "inventory_transaction.completed",
      "inventory_transaction.failed",
      "purchase_order.status_changed"
    ]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "endpoint": {
      "id": "wep_01j5k...",
      "url": "https://yourapp.com/webhooks/boh",
      "events": [
        "inventory_transaction.completed",
        "inventory_transaction.failed",
        "purchase_order.status_changed"
      ],
      "is_active": true,
      "disabled_reason": null,
      "consecutive_failures": 0,
      "created_at": "2026-08-07T14:30:00.000Z",
      "updated_at": "2026-08-07T14:30:00.000Z"
    },
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxx"
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "kind": "webhook_limit_exceeded",
      "message": "Account has reached the maximum of 10 webhook endpoints"
    }
  }
  ```
</ResponseExample>