Trigger Test Webhooks

Simulate webhook deliveries on-demand to test your handler without waiting for real events to happen.

Overview

Some events are hard to cause naturally — for example, case.updated requires a lifecycle transition that only happens through internal collection processes. This endpoint lets you simulate any event so Debitura sends a real webhook delivery to your URL.

How it works:

1. You call POST /v1/webhooks/test with an event type and a real case or client ID
2. Debitura constructs a realistic payload using real entity data (no data is changed — the case doesn't actually move lifecycle)
3. The payload is delivered to your webhook subscriptions through the same pipeline as production: HMAC-signed, with headers, with retries

Nothing happens if you don't have a webhook subscription yet. Set one up first — the response tells you how many subscriptions matched (enqueuedCount).

Available on test environment only. Returns 403 Forbidden in production.

Prerequisites

1. A webhook subscription listening for the event type you want to test — see Webhooks Setup.
2. A real case or client link to reference — the endpoint uses real data to build the payload, but doesn't modify anything.

Trigger a Test Event

POST https://testreferral-api.debitura.com/v1/webhooks/test
XApiKey: YOUR_API_KEY
Content-Type: application/json

Case Events

For case.created and case.updated, provide a caseId belonging to one of your linked clients:

case.updated

{
  "eventType": "case.updated",
  "caseId": "c197daa6-e6b5-443e-8498-867d98c44642",
  "oldLifecycle": "Active",
  "newLifecycle": "Closed"
}

For case.created, only eventType and caseId are required.

Field	Required	Description
eventType	Yes	case.created or case.updated
caseId	Yes	GUID of a real case belonging to a linked client
oldLifecycle	No	case.updated only. Defaults to the case's current lifecycle
newLifecycle	No	case.updated only. Defaults to Closed

Client Events

For client.linked, client.link_declined, client.onboarding.poa_signed, and client.onboarding.contract_signed, provide an externalTenantId:

client.linked

{
  "eventType": "client.linked",
  "externalTenantId": "tenant-11223"
}

Field	Required	Description
eventType	Yes	One of the 4 client event types listed in Webhooks
externalTenantId	Yes	Your identifier for an active client link

Response

{
  "eventType": "case.updated",
  "enqueuedCount": 1,
  "message": "Test event enqueued to 1 subscription(s). Check your webhook endpoint for delivery."
}

An enqueuedCount of 0 means no active subscription is listening for this event type.

Error Handling

Status	Cause	Solution
400 Bad Request	Invalid event type	Use one of the supported event types
400 Bad Request	Missing caseId or externalTenantId	Provide the required field for the event type
403 Forbidden	Production environment	Only available on test (testreferral-api.debitura.com)
404 Not Found	Case or client link not found	Verify the ID exists and belongs to your partner account

See Error Handling for the full error response format.