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

# Create subscription

> Register a new webhook subscription

Register a delivery URL.

<Warning>The response includes `secret` (a `whsec_…` signing secret) **once**. Store it on receipt — only the `secretPrefix` is retrievable later.</Warning>

<Info>**Scope** `webhooks:write` · rate-limited</Info>

## Headers

<ParamField header="Authorization" type="string" required>
  API key.
</ParamField>

## Request body

<ParamField body="url" type="string" required>
  Endpoint URL. Must be `https://`. Rejected with `400` if it's a private IP, loopback, or metadata host.
</ParamField>

<ParamField body="events" type="string[]" required>
  Non-empty list of event types. Allowed: `payout.created`, `payout.status.updated`.
</ParamField>

<ParamField body="label" type="string">
  Optional human-readable label for the dashboard. Never sent to your endpoint.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Subscription UUID.
</ResponseField>

<ResponseField name="secret" type="string">
  The signing secret in plaintext. Returned only on create — store it immediately.
</ResponseField>

<ResponseField name="secretPrefix" type="string">
  First few characters of the secret for partner-side identification on subsequent reads.
</ResponseField>

<ResponseField name="status" type="string">
  Always `active` on a new subscription.
</ResponseField>

The other fields (`url`, `events`, `label`, `lastSuccessAt`, `lastFailureAt`, `createdAt`, `updatedAt`) match the shape on [List subscriptions](/api-reference/webhooks/subscriptions/list).

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "1c84203c-b4e3-40de-83a9-51bc0d9c991f",
    "url": "https://hooks.example.com/teel",
    "events": ["payout.created", "payout.status.updated"],
    "status": "active",
    "secretPrefix": "whsec_Pdt_BP",
    "secret": "whsec_Pdt_BP3ft-nIDl86430kZrGEy8qd7zB4pCUmeU1GVB0",
    "label": "Production receiver",
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "createdAt": "2026-05-27T09:30:00Z",
    "updatedAt": "2026-05-27T09:30:00Z"
  }
  ```
</ResponseExample>

## Errors

| Status | Meaning                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| `400`  | Invalid URL (not https, missing host, private IP, metadata host) or unknown event type. |
| `409`  | You've reached the per-account limit (25). Delete or pause an existing one first.       |