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

# Create webhook

<Info>
  **Pre-release** — contact your Fortary account team for access.
</Info>

<Warning>
  **Illustrative reference.** These examples show the shape of the API and are provided for early evaluation while it is still being finalized. Field names and response details may change before the API is released. A complete reference, generated directly from the live API, will replace these examples once it is available.
</Warning>

Creates a webhook. Requires the `webhook:manage` scope.

## Request

```bash theme={null}
curl -X POST https://customer-api.fortary.io/v1/webhooks \
  -H "Authorization: Bearer fort_..." \
  -H "Content-Type: application/json" \
  -d '{
    "entityIds": ["entity_7c1e4a0c2f"],
    "url": "https://example.com/fortary/webhooks",
    "eventKinds": ["transaction.confirmed", "transaction.failed"],
    "vaultIds": null,
    "notificationEmail": "ops@example.com",
    "description": "Treasury reconciliation"
  }'
```

* **`entityIds`** — the entities this webhook covers (at least one).
* **`url`** — the HTTPS endpoint that receives signed `POST`s.
* **`eventKinds`** — exact [event kinds](/api/reference/webhooks/event-types) to deliver; no wildcards.
* **`vaultIds`** *(optional)* — vault allowlist for vault-scoped events; `null` means all vaults.
* **`notificationEmail`** *(optional)* — recipient of operational notices; defaults to the key owner's email.
* **`description`** *(optional)* — free-text label, max 500 characters.

## Response

```json theme={null}
{
  "id": "whs_9b2f4e1a7c",
  "entityIds": ["entity_7c1e4a0c2f"],
  "url": "https://example.com/fortary/webhooks",
  "notificationEmail": "ops@example.com",
  "eventKinds": ["transaction.confirmed", "transaction.failed"],
  "vaultIds": null,
  "status": "ENABLED",
  "disabledReason": null,
  "consecutiveExhaustedCount": 0,
  "lastDeliveredAt": null,
  "description": "Treasury reconciliation",
  "createdAt": "2026-06-10T09:12:44Z",
  "updatedAt": "2026-06-10T09:12:44Z",
  "secret": "whsec_mB4tQ9..."
}
```

The webhook fields are described in [Get webhook](/api/reference/webhooks/get-webhook).

<Warning>
  **`secret` is returned exactly once** — here and on [rotation](/api/reference/webhooks/rotate-webhook-secret). Store it in your secret manager now; it cannot be retrieved later.
</Warning>

An entity can be covered by at most **20 active webhooks**; creating one beyond the cap returns `409`.

Errors follow the standard [error envelope](/api/concepts/errors).