Create a new webhook subscription.

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:

{
  "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"
  }
}