---
title: "Register a webhook endpoint"
method: POST
path: "/webhooks"
tags: ["webhooks"]
---

# Register a webhook endpoint

`POST /webhooks`

Registers a URL to receive webhook events. The HMAC signing secret
is returned only in the creation response — store it securely.
Payloads are signed with HMAC-SHA256 and delivered in the
X-Webhook-Signature header.

## Headers

- `Idempotency-Key` string

## Request body

- CreateWebhookRequest
  - `url` string, uri, required
  - `events` string[] — Event types to subscribe to (empty = all)

## Response `201`

Webhook endpoint created (includes secret)

- WebhookEndpoint
  - `id` string, uuid, required
  - `tenantId` string, uuid, required
  - `url` string, uri, required
  - `events` string[]
  - `status` 'ACTIVE' | 'DISABLED', required
  - `secret` string — Only returned on creation
  - `createdAt` string, date-time, required

---

[API](https://skmtc.net/quantum-chain-pte-ltd/apis/qustody-api.md) · [All operations](https://skmtc.net/quantum-chain-pte-ltd/apis/qustody-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/quantum-chain-pte-ltd/qustody-api/revisions/ecb2cea3c096/schema)