Skip to main content

Webhook Setup & Configuration

Configure webhooks to receive real-time notifications when client onboarding and case events occur.

Create Webhook Subscription​

Create webhook request
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",
    "case.created",
    "case.updated"
  ]
}
201Created
Response
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://your-platform.com/webhooks/debitura",
  "events": ["client.linked", "case.created", "case.updated"],
  "isActive": true,
  "createdUtc": "2026-01-31T15:23:45Z",
  "updatedUtc": "2026-01-31T15:23:45Z",
  "disabledReason": null,
  "secret": "dGhpc2lzYWJhc2U2NGVuY29kZWRzZWNyZXQ="
}
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.

Verify the webhook signature before processing events.

Managing Webhooks​

List Webhooks​

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

Update Webhook​

Update 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 Webhook​

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

Test Your Webhook​

After creating a subscription, use the test endpoint to trigger a delivery and verify your handler works end-to-end (signature verification, payload parsing, response handling):

Trigger a test event (test environment only)
POST https://testreferral-api.debitura.com/v1/webhooks/test
XApiKey: your_partner_api_key_here
Content-Type: application/json

{
  "eventType": "case.updated",
  "caseId": "your-case-id-here"
}

See Trigger Test Webhooks for all supported event types and options.

For event schemas and payload structures, see Webhooks Overview. Production patterns and reliability strategies are covered in Webhooks Best Practices.