---
title: "Register a webhook subscription"
method: POST
path: "/api-regulated/v1/webhook-subscriptions"
tags: ["Webhooks"]
---

# Register a webhook subscription

`POST /api-regulated/v1/webhook-subscriptions`

## Request

- Base URL: `https://api.currencyguard.com`
- URL: `https://api.currencyguard.com/api-regulated/v1/webhook-subscriptions`
- Auth: OAuth 2 (implicit, authorization URL `https://auth.currencyguard.com/oauth2/authorize`, scopes: `regulated.api-clients.canManageWebhooks`)

Creates a subscription and returns the one-time signing secret.

**Required entitlement:** `regulated.api-clients.canManageWebhooks`  
_Entitles the regulated user to create, view, update, rotate, delete, and replay webhook subscriptions for B2B event delivery_

## Request body

- WebhookSubscriptionCreateRequestDTO: Request data for registering a webhook subscription
  - `subscriptionName` string, required: Human-readable name for this subscription, unique within your regulated entity
  - `endpointUrl` string, required: HTTPS endpoint to which signed event payloads will be POSTed

## Response `201`

Subscription created

- WebhookSubscriptionCreatedDTO: Webhook subscription details including the one-time signing secret
  - `id` string, uuid: ID of the created subscription
  - `subscriptionName` string: Subscription name
  - `endpointUrl` string: Endpoint URL
  - `status` string: Subscription status
  - `signingSecret` string: HMAC-SHA256 signing secret — shown only once. Store it securely; it cannot be retrieved later.
  - `createdAt` string: Timestamp of creation in UTC
  - `message` string: Human-readable note about the one-time secret

## Other responses

- `400`: Invalid request — [`http/malformed-request`](/problems/http/malformed-request/)
- `401`: Not authenticated — [`security/authentication-failed`](/problems/security/authentication-failed/)
- `403`: Not authorized — [`security/insufficient-permissions`](/problems/security/insufficient-permissions/)
- `409`: Subscription name already in use — [`http/resource-conflict`](/problems/http/resource-conflict/)
- `500`: Server error — [`server/internal-error`](/problems/server/internal-error/)

---

[API](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external.md) · [All operations](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external/llms.txt) · [OpenAPI document](https://skmtc.dev/currencyguard/apis/currencyguard-trading-system-api-external/revisions/a1f3f854190d?raw)