Skip to main content

Create webhook subscription

POST 
/webhooks

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

v1 Prototype: Only case.created event supported

Validation Rules: • URL must be HTTPS • events array must only contain "case.created" in v1 • 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