Webhooks

Event schemas and payloads for client onboarding, linking, and case events in the Referral Partner API.

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
`X-Debitura-Event`	Event type

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 an existing Debitura client approves your link request (resolves 409 conflict).

Because this event only fires for pre-existing clients approving a link, creditor.isAttributed is always false. You earn fees only for cases submitted through your API using bearer tokens, not for cases the client creates directly.

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

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"
  },
  "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")

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.

Verify the webhook signature before processing events. For subscription management, see Webhook Setup. For production patterns, see Webhook Best Practices.

Payload Structure​

Creditor Object​

Available Events​

client.onboarding.poa_signed​

client.onboarding.contract_signed​

client.linked​

client.link_declined​

case.created​

case.updated​