Webhooks

Subscribe to real-time events for client onboarding, linking, and case status changes.

Create a Webhook Subscription

POST https://referral-api.debitura.com/v1/Webhooks
Content-Type: application/json
XApiKey: your_partner_api_key_here

{
  "Url": "https://your-platform.com/webhooks/debitura",
  "Events": [
    "client.onboarding.poa_signed",
    "client.onboarding.contract_signed",
    "client.linked",
    "client.link_declined",
    "client.link_requested",
    "client.link_expired",
    "case.created",
    "case.updated",
    "case.closed"
  ]
}

Response (200 OK):

{
  "Id": "550e8400-e29b-41d4-a716-446655440000",
  "Url": "https://your-platform.com/webhooks/debitura",
  "Events": ["client.linked", "case.created", "case.updated", "case.closed"],
  "IsActive": true,
  "CreatedUtc": "2026-01-31T15:23:45Z",
  "UpdatedUtc": "2026-01-31T15:23:45Z",
  "DisabledReason": null,
  "Secret": "dGhpc2lzYWJhc2U2NGVuY29kZWRzZWNyZXQ="
}

:::danger Save Your Secret The secret is only returned once during creation. Store it immediately in your secrets manager. You cannot retrieve it later. If lost, regenerate via PUT /v1/Webhooks/{id} with RegenerateSecret: true. :::

Manage Subscriptions

List all webhooks
GET https://referral-api.debitura.com/v1/Webhooks
XApiKey: your_partner_api_key_here

Update a webhook
PUT https://referral-api.debitura.com/v1/Webhooks/{id}
Content-Type: application/json
XApiKey: your_partner_api_key_here

{
  "Url": "https://new-endpoint.com/webhooks",
  "Events": ["client.linked", "case.created"],
  "IsActive": true,
  "RegenerateSecret": false
}

Delete a webhook
DELETE https://referral-api.debitura.com/v1/Webhooks/{id}
XApiKey: your_partner_api_key_here

For the full API reference, see Webhook endpoints.

Payload Structure

All events use a CloudEvents-inspired format with these envelope fields:

Field	Type	Description
`id`	string (UUID)	Unique event ID for idempotency
`specVersion`	string	Always "1.0"
`event`	string	Event type (e.g., "client.linked")
`timestamp`	string (ISO 8601)	When the event occurred
`data`	object	Event-specific payload
`links.client`	string	API URL for this client

HTTP Headers:

Header	Value
`X-Debitura-Signature`	`t={timestamp},v1={signature}`
`X-Debitura-Timestamp`	Unix timestamp

Creditor Object

Client onboarding and linking events include a creditor object with these fields:

Field	Type	Description
`creditor.id`	string (UUID)	Debitura's internal creditor ID
`creditor.companyName`	string	Legal company name
`creditor.registrationNumber`	string	VAT or company registration number (e.g., "DK12345678")
`creditor.countryId`	string (UUID)	Country identifier
`creditor.isAttributed`	boolean	Whether this is an attributed client — determines revenue share eligibility. Not present in `client.link_declined` events.

Available Events

client.onboarding.poa_signed

Fires when a client signs the Power of Attorney during onboarding. This event fires in both standalone PoA signing flows and the main onboarding flow (before contract signing).

client.onboarding.poa_signed payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "specVersion": "1.0",
  "event": "client.onboarding.poa_signed",
  "timestamp": "2026-01-31T15:23:45Z",
  "data": {
    "externalTenantId": "partner-client-123",
    "creditor": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "companyName": "Acme Corporation Ltd",
      "registrationNumber": "DK12345678",
      "countryId": "456e4567-e89b-12d3-a456-426614174111",
      "isAttributed": false
    },
    "signedAt": "2026-01-31T15:23:45Z"
  },
  "links": {
    "client": "https://api.debitura.com/referral-partner/v1/clients/partner-client-123"
  }
}

Field	Type	Description
`externalTenantId`	string	Your identifier for this client (from onboarding init)
`creditor`	object	Client details — see Creditor Object
`signedAt`	string (ISO 8601)	UTC timestamp when PoA was signed

client.onboarding.contract_signed

Fires when a client completes onboarding by signing the Standard Debt Collection Contract with 2FA verification.

client.onboarding.contract_signed payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "specVersion": "1.0",
  "event": "client.onboarding.contract_signed",
  "timestamp": "2026-01-31T15:23:45Z",
  "data": {
    "externalTenantId": "partner-client-123",
    "creditor": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "companyName": "Acme Corporation Ltd",
      "registrationNumber": "DK12345678",
      "countryId": "456e4567-e89b-12d3-a456-426614174111",
      "isAttributed": false
    },
    "signedAt": "2026-01-31T15:23:45Z"
  },
  "links": {
    "client": "https://api.debitura.com/referral-partner/v1/clients/partner-client-123"
  }
}

Field	Type	Description
`externalTenantId`	string	Your identifier for this client
`creditor`	object	Client details — see Creditor Object
`signedAt`	string (ISO 8601)	UTC timestamp when contract was signed

client.linked

Fires when a client is linked to your partnership through the 409 conflict resolution flow. This covers both paths: the user connecting an existing Debitura account and the user creating a new account from the choice page.

creditor.isAttributed is always false for this event — the user already existed in Debitura before your referral. You earn fees only on cases submitted through your API using bearer tokens. See Attribution for details.

client.linked payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "specVersion": "1.0",
  "event": "client.linked",
  "timestamp": "2026-01-31T15:23:45Z",
  "data": {
    "externalTenantId": "partner-client-123",
    "creditor": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "companyName": "Acme Corporation Ltd",
      "registrationNumber": "DK12345678",
      "countryId": "456e4567-e89b-12d3-a456-426614174111",
      "isAttributed": false
    },
    "linkedAt": "2026-01-31T15:23:45Z"
  },
  "links": {
    "client": "https://api.debitura.com/referral-partner/v1/clients/partner-client-123"
  }
}

Field	Type	Description
`externalTenantId`	string	Your identifier for this client
`creditor`	object	Client details — see Creditor Object. `isAttributed` is always `false` for linked clients.
`linkedAt`	string (ISO 8601)	UTC timestamp when link was approved

client.link_declined

Fires when an existing Debitura client declines your link request (resolves 409 conflict). No link is created, so you cannot submit cases for this client.

client.link_declined payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "specVersion": "1.0",
  "event": "client.link_declined",
  "timestamp": "2026-01-31T15:23:45Z",
  "data": {
    "externalTenantId": "partner-client-123",
    "creditor": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "companyName": "Acme Corporation Ltd",
      "registrationNumber": "DK12345678",
      "countryId": "456e4567-e89b-12d3-a456-426614174111"
    },
    "declinedAt": "2026-01-31T15:23:45Z"
  },
  "links": {
    "client": "https://api.debitura.com/referral-partner/v1/clients/partner-client-123"
  }
}

info

The creditor.isAttributed field is not present in decline events because no link is created.

Field	Type	Description
`externalTenantId`	string	Your identifier for this client
`creditor`	object	Client details — see Creditor Object. Note: `isAttributed` field is absent.
`declinedAt`	string (ISO 8601)	UTC timestamp when link was declined

client.link_requested

Fires when a 409 carry-through triggers a link approval request to an existing Debitura client. This gives you confirmation that the approval URL was issued and the link request is now pending. Use this event to know when a user is in the approval queue — you can prompt them to check their email or the Debitura portal.

client.link_requested payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "specVersion": "1.0",
  "event": "client.link_requested",
  "timestamp": "2026-01-31T15:23:45Z",
  "data": {
    "externalTenantId": "partner-client-123",
    "requestedAt": "2026-01-31T15:23:45Z"
  },
  "links": {
    "client": "https://api.debitura.com/referral-partner/v1/clients/partner-client-123"
  }
}

Field	Type	Description
`externalTenantId`	string	Your identifier for this client
`requestedAt`	string (ISO 8601)	UTC timestamp when the link request was issued

client.link_expired

Fires when a pending link approval request expires without the client acting. Link requests expire after 7 days by default (configurable per partner, maximum 30 days). Once you receive this event, call POST /clients again with the same externalTenantId to generate a new approval URL and restart the flow.

client.link_expired payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "specVersion": "1.0",
  "event": "client.link_expired",
  "timestamp": "2026-01-31T15:23:45Z",
  "data": {
    "externalTenantId": "partner-client-123",
    "expiredAt": "2026-02-07T15:23:45Z"
  },
  "links": {
    "client": "https://api.debitura.com/referral-partner/v1/clients/partner-client-123"
  }
}

Field	Type	Description
`externalTenantId`	string	Your identifier for this client
`expiredAt`	string (ISO 8601)	UTC timestamp when the link request expired

case.created

Fires when a new collection case is created for any linked client.

case.created payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "specVersion": "1.0",
  "event": "case.created",
  "timestamp": "2026-01-31T15:23:45Z",
  "data": {
    "externalTenantId": "partner-client-123",
    "caseId": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "Q8OAXF3W",
    "lifecycle": "Pending contract signing",
    "creditorReference": "INV-001",
    "creditorId": "789e4567-e89b-12d3-a456-426614174222"
  },
  "links": {
    "client": "https://api.debitura.com/referral-partner/v1/clients/partner-client-123"
  }
}

Field	Type	Description
`externalTenantId`	string	Your identifier for the client who owns this case
`caseId`	string (UUID)	Debitura's internal case ID
`reference`	string	Human-readable case reference (e.g., "Q8OAXF3W")
`lifecycle`	string	Initial lifecycle state of the case at creation time — see Lifecycle States for all values
`creditorReference`	string \| null	The case reference you provided in your original `POST /clients` submission (echoed back). Use this to correlate `case.created` events with your submissions — especially on the 409 path where cases are created asynchronously. Null if no reference was submitted.
`creditorId`	string (UUID)	Debitura's internal creditor ID for the client who owns this case

case.updated

Fires when a case lifecycle state changes for any linked client.

case.updated payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "specVersion": "1.0",
  "event": "case.updated",
  "timestamp": "2026-01-31T15:23:45Z",
  "data": {
    "externalTenantId": "partner-client-123",
    "caseId": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "Q8OAXF3W",
    "oldLifecycle": "Active",
    "newLifecycle": "Closed"
  },
  "links": {
    "client": "https://api.debitura.com/referral-partner/v1/clients/partner-client-123"
  }
}

Field	Type	Description
`externalTenantId`	string	Your identifier for the client who owns this case
`caseId`	string (UUID)	Debitura's internal case ID
`reference`	string	Human-readable case reference
`oldLifecycle`	string	Previous lifecycle state
`newLifecycle`	string	New lifecycle state

See Case Lifecycle for all lifecycle states and their meanings.

case.closed

Fires when a case reaches its terminal state (closed). This is the final event for a case — no further case.updated events will follow. Use it to show clients whether their case is finally settled and with what outcome.

case.closed payload
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "specVersion": "1.0",
  "event": "case.closed",
  "timestamp": "2026-01-31T15:23:45Z",
  "data": {
    "externalTenantId": "partner-client-123",
    "caseId": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "XAVSVWM7",
    "closeCode": "Paid",
    "closeComment": "Paid in full by debtor"
  },
  "links": {
    "client": "https://api.debitura.com/referral-partner/v1/clients/partner-client-123"
  }
}

Field	Type	Description
`externalTenantId`	string	Your identifier for the client who owns this case
`caseId`	string (UUID)	Debitura's internal case ID
`reference`	string	Human-readable case reference
`closeCode`	string	Reason the case was closed (e.g., "Paid", "Partially paid", "Debtor Insolvent", "Case Never Started")
`closeComment`	string \| null	Optional additional context about the closure

See Case Lifecycle for all close codes and their meanings.

Verify the webhook signature before processing events. For production patterns, see Webhook Best Practices. To test your handler, see Webhook Testing.

Business context: See Webhook events (business meaning glossary) for what each event means in business terms.

Create a Webhook Subscription​

Manage Subscriptions​

Payload Structure​

Creditor Object​

Available Events​

client.onboarding.poa_signed​

client.onboarding.contract_signed​

client.linked​

client.link_declined​

client.link_requested​

client.link_expired​

case.created​

case.updated​

case.closed​