> ## 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.

# Webhook events

> Supported webhook event types and their resource payloads.

All events use the common webhook envelope. The `type` identifies the event and `data` contains the affected resource.

## Test

| Event          | When it is sent                                                  |
| -------------- | ---------------------------------------------------------------- |
| `webhook.test` | A user selects **Send test webhook** on the API Information page |

The test event contains `{"message":"This is a test webhook from BillingServ."}`.

## Payments

| Event               | When it is sent                                    |
| ------------------- | -------------------------------------------------- |
| `payment.succeeded` | A transaction is recorded with a successful status |
| `payment.failed`    | A transaction is recorded with a failed status     |

Payment data fields:

| Field            | Type              | Description                       |
| ---------------- | ----------------- | --------------------------------- |
| `id`             | integer           | BillingServ transaction record ID |
| `transaction_id` | string or null    | Payment provider transaction ID   |
| `invoice_id`     | integer or null   | Associated invoice                |
| `customer_id`    | integer           | Associated customer               |
| `gateway`        | string or null    | Payment gateway identifier        |
| `amount`         | money string      | Transaction amount                |
| `currency_id`    | integer           | BillingServ currency ID           |
| `status`         | string            | `succeeded` or `failed`           |
| `created_at`     | date-time or null | Transaction creation time         |

## Customers

| Event               | When it is sent                 |
| ------------------- | ------------------------------- |
| `customer.created`  | A customer is created           |
| `customer.updated`  | A public customer field changes |
| `customer.deleted`  | A customer is deleted           |
| `customer.restored` | A deleted customer is restored  |

Customer data contains `id`, `name`, `email`, `username`, `vat_number`, `email_verified_at`, `created_at`, `updated_at`, and `deleted_at`.

## Invoices

| Event              | When it is sent                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------ |
| `invoice.created`  | An invoice or estimate is created                                                                            |
| `invoice.updated`  | Its customer, order, amounts, currency, status, due date, comments, estimate flag, or invoice number changes |
| `invoice.paid`     | Its status becomes paid                                                                                      |
| `invoice.deleted`  | It is deleted                                                                                                |
| `invoice.restored` | It is restored                                                                                               |

Invoice data fields:

| Field            | Type              | Description                                                                   |
| ---------------- | ----------------- | ----------------------------------------------------------------------------- |
| `id`             | integer           | Invoice ID                                                                    |
| `invoice_number` | integer or string | Customer-facing invoice number                                                |
| `customer_id`    | integer           | Customer ID                                                                   |
| `order_id`       | integer or null   | Associated order                                                              |
| `tax`            | money string      | Tax included on the invoice                                                   |
| `total`          | money string      | Invoice total                                                                 |
| `currency_id`    | integer           | BillingServ currency ID                                                       |
| `status`         | string            | `unpaid`, `paid`, `overdue`, `refunded`, `cancelled`, `pending`, or `unknown` |
| `due_at`         | date-time or null | Payment due date                                                              |
| `comments`       | string or null    | Invoice comments                                                              |
| `estimate`       | boolean           | Whether the record is an estimate                                             |
| `created_at`     | date-time or null | Creation time                                                                 |
| `updated_at`     | date-time or null | Last update time                                                              |
| `deleted_at`     | date-time or null | Deletion time when deleted                                                    |

An invoice becoming paid can produce both `invoice.updated` and `invoice.paid`. Handle each event ID independently.

## Orders and subscriptions

| Event                    | When it is sent                                           |
| ------------------------ | --------------------------------------------------------- |
| `order.created`          | An order is created                                       |
| `order.updated`          | A public order field or status changes                    |
| `order.deleted`          | An order is deleted                                       |
| `order.restored`         | An order is restored                                      |
| `subscription.cancelled` | An order's status becomes cancelled                       |
| `subscription.renewed`   | A paid invoice represents a renewal for an existing order |

Order and subscription data contains `id`, `customer_id`, `package_id`, `cycle_id`, `price`, `currency_id`, `status`, `domain_name`, `cancellation_type`, `reason`, `last_invoice`, `next_invoice`, `cancelled_at`, `created_at`, `updated_at`, and `deleted_at`. `price` is a money string.

An order cancellation can produce both `order.updated` and `subscription.cancelled`.

## Credit notes

| Event                 | When it is sent          |
| --------------------- | ------------------------ |
| `credit_note.created` | A credit note is created |
| `credit_note.updated` | A credit note changes    |
| `credit_note.deleted` | A credit note is deleted |

Credit note data contains `id`, `credit_note_number`, `invoice_id`, `customer_id`, `amount`, `tax_amount`, `currency_id`, `reason`, `added_to_account_credit`, `issued_at`, `created_at`, and `updated_at`. Amounts are money strings.

## Support

| Event                            | When it is sent                         |
| -------------------------------- | --------------------------------------- |
| `support_ticket.created`         | A support ticket is created             |
| `support_ticket.updated`         | An audited ticket field changes         |
| `support_ticket.deleted`         | A support ticket is deleted             |
| `support_ticket.message_created` | A reply or message is added to a ticket |

Ticket data contains `id`, `customer_id`, `order_id`, `subject`, `status`, `priority`, `department`, `assignee_id`, `contact_name`, `email_address`, `last_action`, `sla_due_at`, `first_response_at`, `created_at`, and `updated_at`.

Ticket message data contains `id`, `ticket_id`, `author_id`, `message`, and `created_at`. The `message` can contain sanitized HTML and should be escaped or sanitized before rendering in your own interface.