---
title: "Create a webhook subscription"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Create a webhook subscription

`POST /webhooks`

## Request

- Base URL: `https://api.imprezahost.com/v1`
- URL: `https://api.imprezahost.com/v1/webhooks`
- Auth: API key in header `X-API-Key` and API key in header `X-API-Secret`

Creates a subscription that receives `application/json` `POST` requests
for the chosen event types. Each delivery includes:

- `X-Impreza-Signature: sha256=<hex>` — HMAC-SHA256 of the raw body
  using the subscription's `secret`.
- `X-Impreza-Event` — concrete event type
- `X-Impreza-Event-Id` — unique event identifier (`evt_...`)
- `X-Impreza-Delivery-Attempt` — delivery attempt counter

The `secret` is returned **once** in the response. Store it securely;
it cannot be retrieved later. Use `POST /webhooks/{id}/rotate-secret`
to generate a new one.

Subscriptions support wildcards: `vps.*` matches every VPS event,
`*` matches everything.

On creation, a `webhook.test` probe event is enqueued for delivery
so you can verify your endpoint works.

## Request body

- object
  - `url` string, uri, required
  - `events` string[], required
  - `description` string

## Response `201`

Subscription created — secret returned ONCE

## Other responses

- `400`: Validation failed on the request body or query parameters
- `409`: Subscription limit reached

---

[API](https://skmtc.dev/imprezahost/apis/impreza-host-public-api.md) · [All operations](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/revisions/db86511f604f?raw)