Webhooks

Base URL: https://referral-api.debitura.com
Authentication: API key in the XApiKey header

Get all webhooks for the authenticated referral partner

GET/v1/Webhooks

Returns all webhook subscriptions with their configuration (URL, events, status). Note: Secrets are never included in GET responses.

Returns

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

iduuid
Unique identifier for the webhook subscription.
urlstringnullable
The HTTPS URL where webhook events will be delivered.
eventsarray of stringsnullable
Array of event types this subscription is interested in.
isActiveboolean
Whether this webhook subscription is active.
createdUtcdatetime
Timestamp when the webhook subscription was created (UTC).
updatedUtcdatetime
Timestamp when the webhook subscription was last updated (UTC).
disabledReasonstringnullable
Reason why the webhook was automatically disabled (if IsActive is false).
secretstringnullable
Secret key for HMAC-SHA256 signature verification. Only returned on creation or secret regeneration — never exposed again for security.
isTestModeboolean
True when the subscription has DataClassification.Test classification; false for all other classifications (Production, Demo). Computed as Classification != DataClassification.Production.

Errors

401 API key is missing or invalid

See Error handling.

GET/v1/Webhooks

curl https://referral-api.debitura.com/v1/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/v1/Webhooks

Creates webhook subscription for real-time event notifications.

Available Events:

client.onboarding.poa_signed - Client signed Power of Attorney
client.onboarding.contract_signed - Client signed Service Delivery Agreement
client.linked - Client successfully linked to your account
client.link_declined - Client declined to link
client.link_requested - 409 link request created (awaiting end-user approval)
client.link_expired - 409 link request reached its TTL without approval/decline
case.created - Collection case created for linked client
case.updated - Collection case lifecycle changed (e.g., Active → Closed)
case.closed - Collection case closed (terminal state)
cases.replay_failed - A stored case payload failed to create during 409 carry-through (retry via the Customer API)

Security: Response includes Base64-encoded signing secret (shown only once). Store it to verify HMAC-SHA256 signatures on deliveries.

Requirements: HTTPS URL required (HTTP, localhost, and private IPs rejected). Deliveries retry with exponential backoff (8 attempts). Webhook auto-disables after max failures.

Request body

urlstringRequired
The HTTPS URL where webhook events will be delivered. Must be a valid HTTPS URL.
Max 800 characters · URL
eventsarray of stringsRequired
Array of event types to subscribe to.
isTestModeboolean
When true, the subscription is created with DataClassification.Test, meaning it will only receive events for test-classified data. Defaults to false (Production classification).

Returns

200 Webhook created successfully

iduuid
Unique identifier for the webhook subscription.
urlstringnullable
The HTTPS URL where webhook events will be delivered.
eventsarray of stringsnullable
Array of event types this subscription is interested in.
isActiveboolean
Whether this webhook subscription is active.
createdUtcdatetime
Timestamp when the webhook subscription was created (UTC).
updatedUtcdatetime
Timestamp when the webhook subscription was last updated (UTC).
disabledReasonstringnullable
Reason why the webhook was automatically disabled (if IsActive is false).
secretstringnullable
Secret key for HMAC-SHA256 signature verification. Only returned on creation or secret regeneration — never exposed again for security.
isTestModeboolean
True when the subscription has DataClassification.Test classification; false for all other classifications (Production, Demo). Computed as Classification != DataClassification.Production.

Errors

`400`	Invalid request (validation errors)
`401`	API key is missing or invalid

See Error handling.

POST/v1/Webhooks

curl -X POST https://referral-api.debitura.com/v1/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 specific webhook by ID

GET/v1/Webhooks/{id}

Returns webhook configuration including URL, events, active status, and DisabledReason if auto-disabled. Secret is never included (only shown during creation/regeneration).

Path parameters

iduuidRequired

Returns

200 Webhook details

iduuid
Unique identifier for the webhook subscription.
urlstringnullable
The HTTPS URL where webhook events will be delivered.
eventsarray of stringsnullable
Array of event types this subscription is interested in.
isActiveboolean
Whether this webhook subscription is active.
createdUtcdatetime
Timestamp when the webhook subscription was created (UTC).
updatedUtcdatetime
Timestamp when the webhook subscription was last updated (UTC).
disabledReasonstringnullable
Reason why the webhook was automatically disabled (if IsActive is false).
secretstringnullable
Secret key for HMAC-SHA256 signature verification. Only returned on creation or secret regeneration — never exposed again for security.
isTestModeboolean
True when the subscription has DataClassification.Test classification; false for all other classifications (Production, Demo). Computed as Classification != DataClassification.Production.

Errors

`401`	API key is missing or invalid
`404`	Webhook not found or does not belong to this partner

See Error handling.

GET/v1/Webhooks/{id}

curl https://referral-api.debitura.com/v1/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

PUT/v1/Webhooks/{id}

Updates webhook URL, events, or active status. Set RegenerateSecret=true to rotate signing secret (returned in response). Use IsActive=true to re-enable auto-disabled webhooks after fixing delivery issues. Secret only included if RegenerateSecret=true.

Path parameters

iduuidRequired

Request body

urlstringnullable
The new HTTPS URL where webhook events will be delivered. Optional — only provide if changing the URL.
Max 800 characters · URL
eventsarray of stringsnullable
Updated list of event types to subscribe to. Optional — only provide if changing the events. Note: Not supported by the ExternalCustomerAPI — that endpoint returns 400 if this field is set.
isActivebooleannullable
Set to true to enable the webhook, false to disable it. Optional — only provide if changing the active status.
regenerateSecretboolean
Set to true to regenerate the webhook secret. A new secret will be returned in the response.
isTestModebooleannullable
When set, updates the classification of the subscription. True maps to DataClassification.Test; false maps to DataClassification.Production. Omit to leave the current classification unchanged.

Returns

200 Webhook updated successfully

iduuid
Unique identifier for the webhook subscription.
urlstringnullable
The HTTPS URL where webhook events will be delivered.
eventsarray of stringsnullable
Array of event types this subscription is interested in.
isActiveboolean
Whether this webhook subscription is active.
createdUtcdatetime
Timestamp when the webhook subscription was created (UTC).
updatedUtcdatetime
Timestamp when the webhook subscription was last updated (UTC).
disabledReasonstringnullable
Reason why the webhook was automatically disabled (if IsActive is false).
secretstringnullable
Secret key for HMAC-SHA256 signature verification. Only returned on creation or secret regeneration — never exposed again for security.
isTestModeboolean
True when the subscription has DataClassification.Test classification; false for all other classifications (Production, Demo). Computed as Classification != DataClassification.Production.

Errors

`400`	Invalid request (validation errors)
`401`	API key is missing or invalid
`404`	Webhook not found or does not belong to this partner

See Error handling.

PUT/v1/Webhooks/{id}

curl -X PUT https://referral-api.debitura.com/v1/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/v1/Webhooks/{id}

Permanently deletes webhook subscription. Cannot be undone. Consider setting IsActive=false to temporarily disable instead. Delivery history is lost after deletion.

Path parameters

iduuidRequired

Returns

204 Webhook deleted successfully — no response body.

Errors

`401`	API key is missing or invalid
`404`	Webhook not found or does not belong to this partner

See Error handling.

DELETE/v1/Webhooks/{id}

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

Response

204 Webhook deleted successfully. No response body.

Trigger a test webhook event (test environment only)

POST/v1/Webhooks/test

Triggers a realistic webhook delivery through the real pipeline (queue → dispatcher → HMAC-signed HTTP delivery).

⚠️ TEST ENVIRONMENT ONLY - Returns 403 in production. Use testreferral-api.debitura.com for testing.

How it works:

Looks up real entity data (case or client link) to construct a realistic payload
Publishes through the same pipeline as production events (signature verification, retries, etc.)
Returns immediately after enqueueing — delivery is async via Azure Queue

Case events (case.created, case.updated, case.closed):

Requires caseId — must be a real case belonging to a linked client
For case.updated: optionally provide oldLifecycle and newLifecycle (defaults to current → Closed)
For case.closed: optionally provide closeCode and closeComment (defaults to Paid)

Client events (client.linked, client.link_declined, client.link_requested, client.link_expired, client.onboarding.poa_signed, client.onboarding.contract_signed):

Requires externalTenantId — must be an active client link belonging to your account

Request body

eventTypestringRequired
The webhook event type to trigger (e.g. "case.updated", "client.linked")
caseIduuidnullable
Required for case.created, case.updated, and case.closed events
collectionRequestIduuidnullable
Required for collection_request.updated.
externalTenantIdstringnullable
Required for client.* events (client.linked, client.link_declined, client.onboarding.*)
oldLifecyclestringnullable
Optional override for case.updated: the "from" lifecycle (defaults to current case lifecycle)
newLifecyclestringnullable
Optional override for case.updated: the "to" lifecycle (defaults to "Closed")
closeCodestringnullable
Optional override for case.closed: the close code (defaults to "Paid")
closeCommentstringnullable
Optional override for case.closed: a close comment

Returns

200 Test event enqueued successfully

eventTypestringnullable
enqueuedCountinteger
messagestringnullable

Errors

`400`	Invalid request (missing required fields or invalid event type)
`401`	API key is missing or invalid
`403`	Endpoint not available in production environment
`404`	Case or client link not found

See Error handling.

POST/v1/Webhooks/test

curl -X POST https://referral-api.debitura.com/v1/Webhooks/test \
  -H "XApiKey: $DEBITURA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "string"
  }'

Response

{
  "eventType": "string",
  "enqueuedCount": 42,
  "message": "Payment plan agreed with the debtor."
}