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

# Create webhook

`POST /webhooks`

Creates a new webhook subscription. The response includes a `secret` that you should store securely — it is used to verify webhook signatures and is only returned once at creation time.

## Request body

- WebhookCreate
  - `url` string, required — The HTTPS URL that will receive webhook events. Must be publicly accessible. Max 2048 characters.
  - `events` WebhookEvent[], required — List of events to subscribe to. At least one event is required.
  - `enabled` boolean — Whether the webhook is active. Set to `false` to create it in a disabled state.

## Response `201`

The created webhook including the signing secret.

- WebhookCreateResponse
  - `id` string, required — Webhook ID.
  - `url` string, required — The registered URL.
  - `events` WebhookEvent[], required — Subscribed events.
  - `enabled` boolean, required — Whether the webhook is active.
  - `created_at` string, date-time, required — ISO 8601 timestamp.
  - `updated_at` string, date-time, required — ISO 8601 timestamp.
  - `secret` string, required — HMAC signing secret. Store this securely — it is only returned on creation.

## Other responses

- `400` — Invalid request parameters.
- `401` — Authentication required.
- `422` — Validation Error

---

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