---
title: "Create Webhook Subscription"
method: POST
path: "/api/v1/webhook-subscriptions"
tags: ["Webhook Subscriptions"]
---

# Create Webhook Subscription

`POST /api/v1/webhook-subscriptions`

Create a new webhook subscription to receive events

## Request body

- WebhookSubscriptionRequest — Webhook subscription request configuration
  - `webhookSubscription` object, required
    - `url` string, uri, required — HTTPS URL that will receive webhook events
    - `enabled` boolean — Whether the webhook subscription is active
    - `subscribedEvents` string[], required — List of events to subscribe to
    - `entityId` string — If your organisation has multiple entities, you can scope the webhook subscription to a specific entity. If not provided, the webhook subscription will be scoped to the organisation.

## Response `201`

Webhook subscription created successfully

- object
  - `data` WebhookSubscriptionResponse
    - `id` string — Unique identifier for the webhook subscription
    - `type` 'webhookSubscription' — Type of the resource
    - `attributes` object
      - `url` string, uri — HTTPS URL that will receive webhook events
      - `secretKey` string — Secret key used to sign webhook payloads
      - `enabled` boolean — Whether the webhook subscription is active
      - `scopeType` 'organisation' | 'entity' — Scope type for the webhook subscription
      - `scopeName` string — Name of the scope
      - `subscribedEvents` string[] — List of events subscribed to

## Other responses

- `400` — Bad Request - Invalid webhook subscription data
- `401` — Unauthorized - Invalid API key
- `422` — Unprocessable Entity - Invalid webhook URL or configuration

---

[API](https://skmtc.dev/passentry/apis/passentry-api.md) · [All operations](https://skmtc.dev/passentry/apis/passentry-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/passentry/passentry-api/revisions/3b24e067f9d9/schema)