# Create a subscription

> Each user can hold at most 10 subscriptions that have not been deleted (disabled ones count); creating an 11th returns 400 toomanysubscriptions.

Source: https://warmerly.com/docs/webhooks/create-a-subscription

```text
POST /webhooks/subscriptions
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string (1-120 chars) | Yes | A label to identify the subscription. |
| `targetUrl` | string (URL) | Yes | Must be a public `https://` URL. Non-https URLs, URLs with a username or password, localhost, `.local` and `.internal` names, and private, link-local or reserved IP addresses are rejected. The hostname is checked again at delivery time. |
| `eventTypes` | string[] | Yes | One or more values from [Event types](https://warmerly.com/docs/webhooks/create-a-subscription#event-types), at most 16 entries. |

Each user can hold at most **10 subscriptions that have not been deleted** (disabled ones count); creating an 11th returns `400 too_many_subscriptions`.

```bash
curl -X POST https://app.warmerly.com/api/v1/webhooks/subscriptions \
  -H "X-Api-Key: wmv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mailbox alerts",
    "targetUrl": "https://example.com/hooks/warmerly",
    "eventTypes": ["score_drop", "auto_paused", "oauth_disconnected"]
  }'
```

`201 Created`:

```json
{
  "subscription": {
    "id": "e5b3a7c2-8d4e-4f0a-9c2b-6a1d3e8f5c7b",
    "name": "Mailbox alerts",
    "targetUrl": "https://example.com/hooks/warmerly",
    "eventTypes": ["score_drop", "auto_paused", "oauth_disconnected"]
  },
  "secret": "8f2a7c9e4b1d6f3a9c2e5b8d1a4f7c9e6b3d8a1f4c7e9b2d5a8f1c4e7b9d3a6f"
}
```

**`secret` is only ever returned in full here.** Store it, as it's used to verify the `X-Warmerly-Signature` header on every delivery (see [Verifying deliveries](https://warmerly.com/docs/webhooks/create-a-subscription#verifying-deliveries) below). It cannot be retrieved again; delete the subscription and create a new one if you lose it.

Errors: `400 bad_request` (`invalid_body` for a malformed request, or `unknown_event_types` with `details: { unknown: [...] }` if `eventTypes` contains a value not in the table above), `403 agency_plan_required` if your plan doesn't include webhooks.

## More from Webhooks

- [List subscriptions](https://warmerly.com/docs/webhooks/list-subscriptions): Returns your active (non-revoked) subscriptions. The secret is masked to its last 4 characters, it's only…
- [Update a subscription](https://warmerly.com/docs/webhooks/update-a-subscription): Currently the only supported update is toggling active, there's no way to change targetUrl or eventTypes in…
- [Delete a subscription](https://warmerly.com/docs/webhooks/delete-a-subscription): Revokes (soft-deletes) the subscription; deliveries stop immediately. Not gated on plan tier, a downgraded…