> ## Documentation Index
> Fetch the complete documentation index at: https://creditor-documentation.debbiecollect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> How Debbie pushes events to your system

The endpoints in this reference let you push data into the platform and read it
back. Webhooks are the other direction: Debbie calls an endpoint of yours when
something happens on one of your cases, so your system does not have to poll
for it.

## Setting one up

Add a webhook in the creditor portal under *Developers → Webhooks*, or with
[Create webhook](/api-reference/endpoints/webhooks/create). You give it a URL
and the list of events you want.

A webhook you create is bound to your creditor and **only ever receives events
for your own cases** — there is nothing to filter on your side.

## Delivery

Every delivery is a `POST` with a JSON body of the shape:

```json theme={null}
{
  "event": "billings.create",
  "time": "2026-06-04T09:12:44.021Z",
  "data": { "...": "..." }
}
```

* Debbie sends an `X-Verification-Token` header with the token issued when the
  webhook was created. **Verify it on every request** before acting on the
  payload.
* Any non-2xx response counts as a failure. The first delivery is attempted
  immediately; a failure is then retried up to 7 more times with exponential
  backoff — roughly 1, 3, 8, 21, 55, 149 and 404 minutes after the previous
  attempt, about eleven hours end to end.
* Respond quickly and process asynchronously. Acknowledge with 200 as soon as
  the payload is persisted rather than after your own downstream work has
  finished.
* Retries mean a delivery can arrive more than once with an unchanged body, so
  make the handler idempotent. Key it on the identifiers the event carries:
  `billingId` for `billings.create`, and `caseId` — together with `status` — for
  `cases.*`.

## Events

| Event                                                        | Why you want it                                                                                          |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| [`cases.create`](/api-reference/webhooks/cases.create)       | A case was opened for you                                                                                |
| [`cases.update`](/api-reference/webhooks/cases.update)       | A case changed, including status transitions and the reason a case ended                                 |
| [`cases.delete`](/api-reference/webhooks/cases.delete)       | A case was deleted                                                                                       |
| [`billings.create`](/api-reference/webhooks/billings.create) | A settlement was created — fetch what it is made up of, see the [Settlements](/guides/settlements) guide |

These four are the only events a creditor webhook can subscribe to today.

<Note>
  There is no event for a payment landing on a case. Payments reach your books
  through the settlement — `billings.create` and the two endpoints in the
  [Settlements](/guides/settlements) guide — and the creditor portal shows them
  as they come in. If being notified per payment matters to your integration,
  tell your debt collection partner.
</Note>