Skip to main content

Create 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 → Legal)
  • case.closed - Case closed
  • payment.created - Payment registered 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"
  }
}

Request​

Responses​

Webhook created successfully