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

# Webhooks overview

> Receive BillingServ events in your own application.

BillingServ webhooks send an HTTPS `POST` request to your system when supported customer, payment, invoice, order, subscription, credit note, or support activity occurs.

One webhook URL is configured per BillingServ account. All event types are delivered to that URL. Leave the field blank to disable webhooks.

## Configure your endpoint

1. Build a public HTTPS endpoint that accepts JSON `POST` requests.
2. Open **Admin → API Information** in BillingServ.
3. Enter your endpoint in **Webhook URL** and save it.
4. Select **Send test webhook**.
5. Confirm your endpoint receives a `webhook.test` event and returns a successful response.

Webhook URLs must:

* Use `https://`.
* Use a publicly resolvable host or public IP address.
* Be no longer than 2,048 characters.
* Not contain embedded URL credentials.
* Not point to localhost, private networks, or reserved IP ranges.

Redirects are not followed. Configure the final destination URL directly.

## Request format

Every delivery uses the same envelope:

```json theme={null}
{
  "id": "24399ed2-4ec9-4296-98a8-290f77015823",
  "type": "invoice.paid",
  "created_at": "2026-07-16T09:57:22.577661Z",
  "data": {
    "id": 1263,
    "invoice_number": 21,
    "customer_id": 2,
    "order_id": null,
    "tax": "0.00",
    "total": "100.00",
    "currency_id": 4,
    "status": "paid"
  }
}
```

The request also includes:

| Header          | Description                                        |
| --------------- | -------------------------------------------------- |
| `User-Agent`    | `BillingServ-Webhooks/1.0`                         |
| `Webhook-Id`    | Unique delivery event ID; matches the payload `id` |
| `Webhook-Event` | Event name; matches the payload `type`             |
| `Content-Type`  | `application/json`                                 |

Money values are strings with two decimal places to avoid floating-point rounding. Dates use ISO 8601 in UTC. Optional values may be `null`.

## Delivery and retries

Your endpoint should persist or enqueue the event and respond within 10 seconds. Return a `2xx` response only after accepting the event.

Failed deliveries are attempted up to five times. Retries use increasing delays of approximately 1 minute, 5 minutes, 30 minutes, and 2 hours. Deliveries can therefore arrive more than once or out of order.

Use the payload `id` as an idempotency key and make event processing safe to repeat. Do not depend on delivery order; use `created_at` and the resource timestamps when ordering changes matters.

See the [event and payload reference](/api-reference/webhooks/events) or [build an endpoint](/api-reference/webhooks/build-an-endpoint).