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

# Create a new webhook subscription.

`POST /webhooks`

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

**Available Events:**
- `case.created` - New collection case created
- `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

**Validation Rules:**
- URL must be HTTPS
- events array must contain only valid event types
- URL must be publicly reachable
- Private IP addresses are blocked (SSRF protection)

**Returns:**
- Webhook subscription details
- Secret key for HMAC-SHA256 signature verification (shown only once)

**IMPORTANT**: Save the secret immediately - it cannot be retrieved later.

**Webhook Payload Structure:**
Every webhook delivery will contain these headers:
- X-Debitura-Signature: HMAC-SHA256 signature (format: t={timestamp},v1={signature})
- X-Debitura-Timestamp: Unix timestamp of the event
- X-Debitura-Event: Event type (e.g., 'case.created')

**Signature Verification (HMAC-SHA256):**
1. Extract timestamp (t) and signature (v1) from X-Debitura-Signature header
2. Construct signed payload: {timestamp}.{json_body}
3. Compute HMAC-SHA256 using your webhook secret (Base64 decoded)
4. Compare computed signature with v1 value (use constant-time comparison)
5. Verify timestamp is within 5 minutes to prevent replay attacks

**Example Payload:**
```json
{
  "id": "evt_abc123",
  "event": "case.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "caseId": "guid-here",
    "reference": "Q8OAXF3W",
    "creditorReference": "INV-001",
    "status": "Active",
    "amount": 1000.00,
    "currency": "EUR",
    "debtorName": "Debtor Company Ltd"
  }
}
```

## 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
- `422` — Business rule violation

---

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