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

# Create a webhook subscription

`POST /webhooks`

## Request

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

Creates a webhook subscription. Secrets are write-only and are never returned.

`url` must include an endpoint path (`https://api.example.com/webhooks/events`); a bare origin is rejected with 422 because no route on your server would receive the delivery.

`cluster_id` must name a cluster in your workspace, and `realm_id` a realm on that cluster; either one unknown returns 404. A `realm_id` sent without a `cluster_id` must be a realm on one of your workspace's clusters. Omit both to subscribe to every cluster in the workspace.

Required scope: `webhooks:write`

## Request body

- CreateWebhookSubscriptionRequest
  - `name` string, required
  - `url` string, uri, required: Delivery endpoint. Must be an `http` or `https` URL that includes an endpoint path, for example `https://api.example.com/webhooks/events`. A bare origin with no path (or a path of just `/`) is rejected.
  - `source` 'keycloak' | 'platform', required
  - `event_types` string[], required
  - `signing_secret` string, password, required
  - `enabled` boolean
  - `cluster_id` string, uuid
  - `realm_id` string, uuid: Keycloak realm ID. This is a UUID generated by Keycloak.
  - `authorization_header` string, password

## Response `201`

The request has succeeded and a new resource has been created as a result.

- WebhookSubscription: Saved webhook subscription for the authenticated workspace.
  - `id` string, uuid, required
  - `name` string, required
  - `url` string, required
  - `enabled` boolean, required
  - `source` 'keycloak' | 'platform', required
  - `event_types` string[], required
  - `cluster_id` string, uuid
  - `realm_id` string
  - `has_authorization_header` boolean, required
  - `has_signing_secret` boolean, required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `400`: The server could not understand the request due to invalid syntax.
- `401`: Access is unauthorized.
- `402`: Client error
- `403`: Access is forbidden.
- `404`: The server cannot find the requested resource.
- `422`: Client error
- `429`: Client error
- `500`: Server error
- `501`: Server error

---

[API](https://skmtc.dev/skycloak/apis/skycloak-public-api.md) · [All operations](https://skmtc.dev/skycloak/apis/skycloak-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skycloak/apis/skycloak-public-api/revisions/33a69e2ce35f?raw)