Webhooks

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://customer-api.debitura.com
Authentication: API key in the XApiKey header

List all webhook subscriptions for the authenticated creditor.

GET/webhooks

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

Returns

200 List of webhook subscriptions — a list of the objects below.

iduuid
urlstringnullable
eventsarray of stringsnullable
isActiveboolean
createdUtcdatetime
updatedUtcdatetime
disabledReasonstringnullable
secretstringnullable
isTestModeboolean

GET/webhooks

curl https://customer-api.debitura.com/webhooks \
  -H "XApiKey: $DEBITURA_API_KEY"

Response

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

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):

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

Example Payload:

{
  "id": "bfa8af05-4bd1-4fd5-8f80-a6357f99dc59",
  "specVersion": "1.0",
  "event": "case.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "caseId": "72d427c1-c38c-48db-b369-6f4a2e9cad3f",
    "reference": "Q8OAXF3W",
    "lifecycle": "Pending Verification Internal"
  },
  "links": {
    "self": "https://customer-api.debitura.com/Cases/72d427c1-c38c-48db-b369-6f4a2e9cad3f"
  }
}

Request body

urlstringRequired
Max 800 characters · URL
eventsarray of stringsRequired
isTestModeboolean

Returns

201 Webhook created successfully

iduuid
urlstringnullable
eventsarray of stringsnullable
isActiveboolean
createdUtcdatetime
updatedUtcdatetime
disabledReasonstringnullable
secretstringnullable
isTestModeboolean

Errors

`400`	Invalid request
`422`	Business rule violation

See Error handling.

POST/webhooks

curl -X POST https://customer-api.debitura.com/webhooks \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/debitura",
    "events": [
      "string"
    ]
  }'

Response

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

Get a single webhook subscription by ID.

GET/webhooks/{id}

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

Path parameters

iduuidRequired

Returns

200 Webhook subscription found

iduuid
urlstringnullable
eventsarray of stringsnullable
isActiveboolean
createdUtcdatetime
updatedUtcdatetime
disabledReasonstringnullable
secretstringnullable
isTestModeboolean

Errors

404 Webhook not found

See Error handling.

GET/webhooks/{id}

curl https://customer-api.debitura.com/webhooks/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY"

Response

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

Update an existing webhook subscription.

PATCH/webhooks/{id}

Partially updates an existing webhook subscription using HTTP PATCH.

Supported Updates:

Change the webhook URL
Enable or disable the subscription
Regenerate the secret key

Note: Event types cannot be changed after creation. To update event types, delete and recreate the subscription.

Path parameters

iduuidRequired

Request body

urlstringnullable
Max 800 characters · URL
eventsarray of stringsnullable
isActivebooleannullable
regenerateSecretboolean
isTestModebooleannullable

Returns

200 Webhook updated successfully

iduuid
urlstringnullable
eventsarray of stringsnullable
isActiveboolean
createdUtcdatetime
updatedUtcdatetime
disabledReasonstringnullable
secretstringnullable
isTestModeboolean

Errors

`400`	Invalid request
`404`	Webhook not found

See Error handling.

PATCH/webhooks/{id}

curl -X PATCH https://customer-api.debitura.com/webhooks/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

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

Delete a webhook subscription.

DELETE/webhooks/{id}

Deletes a webhook subscription. This operation is permanent.

Path parameters

iduuidRequired

Returns

204 Webhook deleted successfully — no response body.

Errors

404 Webhook not found

See Error handling.

DELETE/webhooks/{id}

curl -X DELETE https://customer-api.debitura.com/webhooks/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31 \
  -H "XApiKey: $DEBITURA_API_KEY"

Response

204 Webhook deleted successfully. No response body.

Send a test event to the webhook endpoint.

POST/webhooks/{id}/test

Sends a synthetic case.created test event to the webhook endpoint.

This is useful for:

Verifying the webhook URL is reachable
Testing your webhook endpoint implementation
Validating signature verification

The test payload will be a realistic case.created event with synthetic data.

Path parameters

iduuidRequired

Returns

200 Test completed

successboolean
Whether the test delivery was successful.
httpStatusCodeintegernullable
HTTP status code returned by the webhook endpoint.
durationMsintegernullable
Duration of the HTTP request in milliseconds.
errorMessagestringnullable
Error message if the delivery failed.
errorCategorystringnullable
Category of the error (TimeoutError, NetworkError, SslError, HttpError, UnknownError).
testPayloadanynullable
The test event payload that was sent.

Errors

404 Webhook not found

See Error handling.

POST/webhooks/{id}/test

curl -X POST https://customer-api.debitura.com/webhooks/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/test \
  -H "XApiKey: $DEBITURA_API_KEY"

Response

{
  "success": true,
  "httpStatusCode": 3,
  "durationMs": 3,
  "errorMessage": null,
  "errorCategory": null,
  "testPayload": null
}

Send a test event to the webhook endpoint.

POST/webhooks/{id}:test

Sends a synthetic case.created test event to the webhook endpoint.

This is useful for:

Verifying the webhook URL is reachable
Testing your webhook endpoint implementation
Validating signature verification

The test payload will be a realistic case.created event with synthetic data.

Path parameters

iduuidRequired

Returns

200 Test completed

successboolean
Whether the test delivery was successful.
httpStatusCodeintegernullable
HTTP status code returned by the webhook endpoint.
durationMsintegernullable
Duration of the HTTP request in milliseconds.
errorMessagestringnullable
Error message if the delivery failed.
errorCategorystringnullable
Category of the error (TimeoutError, NetworkError, SslError, HttpError, UnknownError).
testPayloadanynullable
The test event payload that was sent.

Errors

404 Webhook not found

See Error handling.

POST/webhooks/{id}:test

curl -X POST https://customer-api.debitura.com/webhooks/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31:test \
  -H "XApiKey: $DEBITURA_API_KEY"

Response

{
  "success": true,
  "httpStatusCode": 3,
  "durationMs": 3,
  "errorMessage": null,
  "errorCategory": null,
  "testPayload": null
}

Deprecated

Kept working for existing integrations. Do not build on these.

This endpoint is misnamed and does not actually replay events. Use `GET /webhooks/events?caseId={id}` to inspect delivery history, then `POST /webhooks/events/{eventId}/replay` to re-deliver a specific event.Deprecated

POST/webhooks/{id}/replay

This endpoint was never fully implemented — it counts cases created since sinceUtc and returns the count as eventsReplayed, but does not re-enqueue or redeliver any events. The name "replay" collides with the real POST /webhooks/events/{eventId}/replay endpoint which actually re-delivers.

This endpoint is kept for backward compatibility (additive-only rule) but is deprecated. Integrators should migrate to the event-log + replay-by-id pattern described above.

Path parameters

iduuidRequired

Request body

sinceUtcdatetimeRequired
Replay all case.created events since this timestamp (UTC).

Returns

200 Count of cases since sinceUtc (not events replayed)

eventsReplayedinteger
Number of events that were re-enqueued for delivery.

Errors

`400`	Invalid request
`404`	Webhook not found

See Error handling.

POST/webhooks/{id}/replay

curl -X POST https://customer-api.debitura.com/webhooks/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31/replay \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sinceUtc": "2026-10-01T14:05:00Z"
  }'

Response

{
  "eventsReplayed": 3
}

This endpoint is misnamed and does not actually replay events. Use `GET /webhooks/events?caseId={id}` to inspect delivery history, then `POST /webhooks/events/{eventId}/replay` to re-deliver a specific event.Deprecated

POST/webhooks/{id}:replay

This endpoint is kept for backward compatibility (additive-only rule) but is deprecated. Integrators should migrate to the event-log + replay-by-id pattern described above.

Path parameters

iduuidRequired

Request body

sinceUtcdatetimeRequired
Replay all case.created events since this timestamp (UTC).

Returns

200 Count of cases since sinceUtc (not events replayed)

eventsReplayedinteger
Number of events that were re-enqueued for delivery.

Errors

`400`	Invalid request
`404`	Webhook not found

See Error handling.

POST/webhooks/{id}:replay

curl -X POST https://customer-api.debitura.com/webhooks/3f2b6c1e-8a4d-4b7f-9c2e-5d1a0b9e7f31:replay \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sinceUtc": "2026-10-01T14:05:00Z"
  }'

Response

{
  "eventsReplayed": 3
}