---
title: "Create a new webhook subscription"
method: POST
path: "/v1/Webhooks"
tags: ["Webhooks"]
---

# Create a new webhook subscription

`POST /v1/Webhooks`

Creates webhook subscription for real-time event notifications.

**Available Events:**
- `client.onboarding.poa_signed` - Client signed Power of Attorney
- `client.onboarding.contract_signed` - Client signed Service Delivery Agreement
- `client.linked` - Client successfully linked to your account
- `client.link_declined` - Client declined to link
- `client.link_requested` - 409 link request created (awaiting end-user approval)
- `client.link_expired` - 409 link request reached its TTL without approval/decline
- `case.created` - Collection case created for linked client
- `case.updated` - Collection case lifecycle changed (e.g., Active → Closed)
- `case.closed` - Collection case closed (terminal state)
- `cases.replay_failed` - A stored case payload failed to create during 409 carry-through (retry via the Customer API)

**Security:** Response includes Base64-encoded signing secret (shown only once). Store it to verify HMAC-SHA256 signatures on deliveries.

**Requirements:** HTTPS URL required (HTTP, localhost, and private IPs rejected). Deliveries retry with exponential backoff (8 attempts). Webhook auto-disables after max failures.

## Request body

- DebituraDomainModelWebhooksDtosCreateWebhookRequest — Request to create a new webhook subscription.
  - `url` string, uri, required — The HTTPS URL where webhook events will be delivered. Must be a valid HTTPS URL.
  - `events` string[], required — Array of event types to subscribe to.
  - `isTestMode` boolean — When true, the subscription is created with `DataClassification.Test`, meaning it will only receive events for test-classified data. Defaults to false (Production classification).

## Response `200`

Webhook created successfully

- DebituraDomainModelWebhooksDtosWebhookDto — Represents a webhook subscription configuration.
  - `id` string, uuid — Unique identifier for the webhook subscription.
  - `url` string, nullable — The HTTPS URL where webhook events will be delivered.
  - `events` string[], nullable — Array of event types this subscription is interested in.
  - `isActive` boolean — Whether this webhook subscription is active.
  - `createdUtc` string, date-time — Timestamp when the webhook subscription was created (UTC).
  - `updatedUtc` string, date-time — Timestamp when the webhook subscription was last updated (UTC).
  - `disabledReason` string, nullable — Reason why the webhook was automatically disabled (if IsActive is false).
  - `secret` string, nullable — Secret key for HMAC-SHA256 signature verification. Only returned on creation or secret regeneration — never exposed again for security.
  - `isTestMode` boolean — True when the subscription has `DataClassification.Test` classification; false for all other classifications (Production, Demo). Computed as `Classification != DataClassification.Production`.

## Other responses

- `400` — Invalid request (validation errors)
- `401` — API key is missing or invalid

---

[API](https://skmtc.net/debitura/apis/debitura-referral-partner-api.md) · [All operations](https://skmtc.net/debitura/apis/debitura-referral-partner-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/debitura/debitura-referral-partner-api/versions/9c466e0e2bf4/schema)