Source: https://docs.debitura.com/api/collection-partner-api/webhooks

# Webhooks — Collection Partner API

Manage webhook subscriptions and inspect the delivery event log. Create subscriptions to receive real-time notifications for case lifecycle events, payments, and chats. Use GET /webhooks/events to verify deliveries and POST /webhooks/events/{id}/replay to re-deliver a specific event.

Base URL: `https://collectionpartner-api.debitura.com`

Authentication: `XApiKey` API key; see [authentication](https://docs.debitura.com/developer-concepts/authentication.md).

Generated from [OpenAPI](https://docs.debitura.com/openapi/collection-partner-api.json). Examples are schema illustrations, not observed responses. Complete schemas, including recursive types, are in OpenAPI.

<a id="list-all-webhook-subscriptions-for-the-authenticated-collection"></a>

## List all webhook subscriptions for the authenticated collection partner.

`GET /webhooks`

Returns all webhook subscriptions for the authenticated collection partner. Secrets are never returned in list operations.

### Response 200

List of webhook subscriptions

- `id` (uuid): 
- `url` (string, nullable): 
- `events` (array of strings, nullable): 
- `isActive` (boolean): 
- `createdUtc` (datetime): 
- `updatedUtc` (datetime): 
- `disabledReason` (string, nullable): 
- `secret` (string, nullable): 
- `isTestMode` (boolean): 

```json
[
  {
    "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
    "url": "https://app.debitura.com/…",
    "events": [
      "string"
    ],
    "isActive": true,
    "createdUtc": "2026-10-01T14:05:00Z",
    "updatedUtc": "2026-10-01T14:05:00Z",
    "disabledReason": null,
    "secret": "string",
    "isTestMode": true
  }
]
```

### Response 401

API key is missing or invalid

<a id="create-a-new-webhook-subscription"></a>

## Create a new webhook subscription.

`POST /webhooks`

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 (application/json)

- `url` (string, required): 
  Max 800 characters; URL.
- `events` (array of strings, required): 
- `isTestMode` (boolean): 

```json
{
  "url": "https://example.com/webhooks/debitura",
  "events": [
    "string"
  ]
}
```

### Response 201

Webhook created successfully

- `id` (uuid): 
- `url` (string, nullable): 
- `events` (array of strings, nullable): 
- `isActive` (boolean): 
- `createdUtc` (datetime): 
- `updatedUtc` (datetime): 
- `disabledReason` (string, nullable): 
- `secret` (string, nullable): 
- `isTestMode` (boolean): 

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "url": "https://app.debitura.com/…",
  "events": [
    "string"
  ],
  "isActive": true,
  "createdUtc": "2026-10-01T14:05:00Z",
  "updatedUtc": "2026-10-01T14:05:00Z",
  "disabledReason": null,
  "secret": "string",
  "isTestMode": true
}
```

### Response 400

Invalid request

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```

### Response 401

API key is missing or invalid

### Response 422

Business rule violation

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```

<a id="get-a-specific-webhook-subscription-by-id"></a>

## Get a specific webhook subscription by ID.

`GET /webhooks/{id}`

Returns details of a specific webhook subscription. Secret is never returned in this operation.

### Path parameters

- `id` (uuid, required): The unique identifier of the webhook subscription.

### Response 200

Webhook subscription found

- `id` (uuid): 
- `url` (string, nullable): 
- `events` (array of strings, nullable): 
- `isActive` (boolean): 
- `createdUtc` (datetime): 
- `updatedUtc` (datetime): 
- `disabledReason` (string, nullable): 
- `secret` (string, nullable): 
- `isTestMode` (boolean): 

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "url": "https://app.debitura.com/…",
  "events": [
    "string"
  ],
  "isActive": true,
  "createdUtc": "2026-10-01T14:05:00Z",
  "updatedUtc": "2026-10-01T14:05:00Z",
  "disabledReason": null,
  "secret": "string",
  "isTestMode": true
}
```

### Response 401

API key is missing or invalid

### Response 404

Webhook not found

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```

<a id="update-an-existing-webhook-subscription"></a>

## Update an existing webhook subscription.

`PUT /webhooks/{id}`

Updates webhook URL, events, or active status. Set RegenerateSecret=true to rotate signing secret (returned in response). Use IsActive=true to re-enable auto-disabled webhooks after fixing delivery issues. Secret only included if RegenerateSecret=true.

### Path parameters

- `id` (uuid, required): The unique identifier of the webhook subscription to update.

### Request body (application/json)

- `url` (string, nullable): 
  Max 800 characters; URL.
- `events` (array of strings, nullable): 
- `isActive` (boolean, nullable): 
- `regenerateSecret` (boolean): 
- `isTestMode` (boolean, nullable): 

```json
{}
```

### Response 200

Webhook updated successfully

- `id` (uuid): 
- `url` (string, nullable): 
- `events` (array of strings, nullable): 
- `isActive` (boolean): 
- `createdUtc` (datetime): 
- `updatedUtc` (datetime): 
- `disabledReason` (string, nullable): 
- `secret` (string, nullable): 
- `isTestMode` (boolean): 

```json
{
  "id": "3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31",
  "url": "https://app.debitura.com/…",
  "events": [
    "string"
  ],
  "isActive": true,
  "createdUtc": "2026-10-01T14:05:00Z",
  "updatedUtc": "2026-10-01T14:05:00Z",
  "disabledReason": null,
  "secret": "string",
  "isTestMode": true
}
```

### Response 400

Invalid request

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```

### Response 401

API key is missing or invalid

### Response 404

Webhook not found

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```

<a id="delete-a-webhook-subscription"></a>

## Delete a webhook subscription.

`DELETE /webhooks/{id}`

Permanently deletes webhook subscription. Cannot be undone. Consider setting IsActive=false to temporarily disable instead.

### Path parameters

- `id` (uuid, required): The unique identifier of the webhook subscription to delete.

### Response 204

Webhook deleted successfully

### Response 401

API key is missing or invalid

### Response 404

Webhook not found

- `error` (string, nullable): Short human-readable error label (legacy field — preserved for backward compatibility).
- `message` (string, nullable): Human-readable error description (legacy field — preserved for backward compatibility).
- `businessErrors` (array of objects, nullable): Canonical structured error array. Consumers should migrate to reading this field.
- `businessErrors[].type` (string, nullable): The type of business error (e.g., "MissingDebtCollectionContract", "MissingPowerOfAttorney", "NoPartnerAvailable").
- `businessErrors[].message` (string, nullable): A human-readable description of the error.
- `businessErrors[].solutionUrl` (string, nullable): A URL where the user can resolve this <i>specific</i> error (e.g., sign a contract).
            

Partners who want a <b>single URL</b> that walks the user through every pending
signing in one chain — instead of forwarding one URL per
`BusinessErrorApiDTO` — should use
SigningHandoff's `CombinedSigningUrl`.
The two are complementary: `SolutionUrl` is granular per-error;
`CombinedSigningUrl` is the chain-walking alternative for signing-related errors.

```json
{
  "error": null,
  "message": "Payment plan agreed with the debtor.",
  "businessErrors": [
    {
      "type": "string",
      "message": "Payment plan agreed with the debtor.",
      "solutionUrl": "https://app.debitura.com/…"
    }
  ]
}
```