---
title: "Register a webhook subscription"
method: POST
path: "/api/2026-01-01/webhooks"
tags: ["Webhooks"]
---

# Register a webhook subscription

`POST /api/2026-01-01/webhooks`

Registers a new webhook subscription for the authenticated partner. The signing secret is returned only in this response and cannot be retrieved again — store it securely. The secret is used to verify that webhook payloads are sent by Jane.

## Request body

- WebhookSubscriptionCreate
  - `event_topic` string, required — The event topic to subscribe to
  - `target_url` string, required — The HTTPS URL that will receive webhook event payloads

## Response `201`

The webhook subscription was registered

- WebhookSubscriptionCreateResponse — Returned on successful registration. The secret is only present here and cannot be retrieved again.
  - `id` string, uuid, required — Unique identifier for the webhook subscription
  - `event_topic` 'APPOINTMENT_BOOKED' | 'APPOINTMENT_CANCELLED' | 'APPOINTMENT_UNCANCELLED' | 'APPOINTMENT_RESCHEDULED', required — The event topic this subscription receives
  - `target_url` string, required — The HTTPS URL that receives webhook event payloads
  - `clinic_guid` integer, required — The clinic identifier this subscription belongs to
  - `status` 'active' | 'inactive', required — Whether the subscription is currently active
  - `updated_at` string, date-time, required — When the subscription was last updated
  - `created_at` string, date-time, required — When the subscription was created
  - `secret` string — HMAC signing secret for verifying webhook payload authenticity. Present only on initial registration.

## Other responses

- `400` — The request body is invalid or missing required fields
- `401` — The request is not authorized
- `403` — The authenticated partner does not have permission to register webhook subscriptions for this clinic
- `409` — A subscription for this event topic already exists
- `422` — The webhook subscription could not be processed due to validation errors
- `503` — The service is temporarily unavailable

---

[API](https://skmtc.net/jane/apis/jdp-api.md) · [All operations](https://skmtc.net/jane/apis/jdp-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/jane/jdp-api/revisions/119f3c4ad601/schema)