---
title: "Create a webhook subscription (Pro+)"
method: POST
path: "/v1/webhooks"
tags: ["webhooks"]
---

# Create a webhook subscription (Pro+)

`POST /v1/webhooks`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/v1/webhooks`
- Auth: API key in header `X-Api-Key`

On each matching published event, POSTs {data: [event], meta} to your `url` (a one-item list, Pro-tier field set regardless of your own tier) with an HMAC-SHA256 signature. `secret` is returned exactly once, in this response only — save it for verifying delivery signatures; it cannot be retrieved again afterward.

## Request body

- WebhookCreate
  - `url` string, uri, required
  - `filter` object

## Response `201`

Successful Response

- WebhookResponse
  - `data` WebhookSubscription, required
    - `id` string, required
    - `url` string, required
    - `filter` object, required
    - `is_active` boolean, required
    - `created_at` string, date-time, required
    - `secret` string, nullable
  - `meta` Meta, required
    - `request_id` string, required
    - `taxonomy_version` string, required
    - `tier` 'free' | 'pro' | 'enterprise', required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/scoopkit/apis/scoopkit-api.md) · [All operations](https://skmtc.dev/scoopkit/apis/scoopkit-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scoopkit/apis/scoopkit-api/revisions/18068781261d?raw)