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

# Create a new webhook subscription.

`POST /webhooks`

## Request

- Base URL: `https://collectionpartner-api.debitura.com`
- URL: `https://collectionpartner-api.debitura.com/webhooks`
- Auth: API key in header `XApiKey`

Creates a new webhook subscription for receiving real-time event notifications.

**Available Events (assigned/working-partner role):**
- `case.assigned` - Case validated by Debitura and assigned to your agency
- `case.updated` - Case lifecycle changed (e.g., Active → Paused). Does not cover engagement phase
  changes (Pre-legal/Legal/Enforcement) — poll `GET /cases/{id}` or `GET /cases/{id}/timeline` for
  the current phase; there is no phase-change event today.
- `case.closed` - Case closed
- `payment.created` - Payment registered on case
- `payment.deleted` - Payment reversed (deleted) on case
- `chat.created` - Chat message created on case

**Managing-role events (explicit opt-in):**
`managed_case.created`, `managed_case.assigned`, `managed_case.updated`, `managed_case.closed`,
`managed_case.declined`, `managed_case.payment.created`, `managed_case.payment.deleted`, `managed_case.chat.created`.
You may configure these subscriptions before managing-webhook delivery is enabled. Notifications remain
inactive until enabled; synthetic managed fire returns 422 while disabled. Notifications contain minimal
event facts; chat body and close/decline comments are omitted. Detailed content uses the authorized managing-case API.
Managed chat notifications and history require the current active engagement. Payment deletion repeats
the original payment snapshot; the event name identifies its reversal.
Existing subscriptions are never automatically opted in.

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

**Requirements:** HTTPS URL required. Deliveries retry with exponential backoff (8 attempts). Webhook auto-disables after max failures.

## Request body

- DebituraDomainModelWebhooksDtosCreateWebhookRequest
  - `url` string, uri, required
  - `events` string[], required
  - `isTestMode` boolean

## Response `201`

Webhook created successfully

- DebituraDomainModelWebhooksDtosWebhookDto
  - `id` string, uuid
  - `url` string, nullable
  - `events` string[], nullable
  - `isActive` boolean
  - `createdUtc` string, date-time
  - `updatedUtc` string, date-time
  - `disabledReason` string, nullable
  - `secret` string, nullable
  - `isTestMode` boolean

## Other responses

- `400`: Invalid request
- `401`: API key is missing or invalid
- `422`: Business rule violation

## Changes

- **2026-10-21** `a7cf0ff022b6`: 4 breaking
  - the `url` request property's maxLength was decreased to `800` (media type: application/json-patch+json)
  - the `url` request property's maxLength was decreased to `800` (media type: application/json)
  - the `url` request property's maxLength was decreased to `800` (media type: text/json)
  - the `url` request property's maxLength was decreased to `800` (media type: application/*+json)

[Operation history](https://skmtc.dev/debitura/apis/debitura-collection-partner-api/changes/webhooks/post.md)

---

[API](https://skmtc.dev/debitura/apis/debitura-collection-partner-api.md) - [All operations](https://skmtc.dev/debitura/apis/debitura-collection-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/debitura/apis/debitura-collection-partner-api/revisions/a7cf0ff022b6?raw)