Source: https://docs.debitura.com/referral-partners/integration-guides/webhook-testing

# Webhook Testing

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

<a id="overview"></a>

## 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](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md) 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.

<a id="prerequisites"></a>

## Prerequisites

1.  **A webhook subscription listening for the event type you want to test** — see [Webhooks Setup](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md).
2.  **A real case or client link to reference** — the endpoint uses real data to build the payload, but doesn't modify anything.

<a id="trigger-a-test-event"></a>

## Trigger a Test Event

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

<a id="case-events"></a>

### Case Events

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

case.updated

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

case.closed

```json
{
  "eventType": "case.closed",
  "caseId": "c197daa6-e6b5-443e-8498-867d98c44642",
  "closeCode": "Paid",
  "closeComment": "Paid in full by debtor"
}
```

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

| Field | Required | Description |
| --- | --- | --- |
| `eventType` | Yes | `case.created`, `case.updated`, or `case.closed` |
| `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` |
| `closeCode` | No | `case.closed` only. Defaults to `"Paid"` |
| `closeComment` | No | `case.closed` only. Optional additional context |

<a id="client-events"></a>

### Client Events

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

client.linked

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

| Field | Required | Description |
| --- | --- | --- |
| `eventType` | Yes | One of the 6 client event types listed in [Webhooks](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md) |
| `externalTenantId` | Yes | Your identifier for an active client link |

<a id="response"></a>

### Response

```json
{
  "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 matching Test-classification subscription was found for this event.

<a id="error-handling"></a>

## Error Handling

| Status | Cause | Solution |
| --- | --- | --- |
| `400 Bad Request` | Invalid event type | Use one of the [supported event types](https://docs.debitura.com/referral-partners/integration-guides/webhooks.md#available-events) |
| `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](https://docs.debitura.com/developer-concepts/error-handling.md) for the full error response format.

For diagnosing failed live deliveries (not test-trigger errors), see [Webhook Troubleshooting](https://docs.debitura.com/developer-concepts/webhooks/troubleshooting.md).
