# Staying up to date

How Lavanda tells your systems that something changed — using **webhooks** and the **AR API**.

## The pattern

1. A finance document changes in Lavanda.
2. Lavanda sends a **webhook** containing the **document ID** and the type of change.
3. You call the **AR API** with that ID to get the latest full details.
4. You update your ledger or warehouse.

Webhooks are alerts only. The AR API response is your source of truth.

## Where to see available webhooks

The full event catalogue (event names, payload shapes, schemas) is published at
<https://webhooks-docs.lavanda.app/>

Once your webhook application is configured, you can also browse and test events in the Svix portal
provided by Lavanda.

## After each webhook, refresh

- The document named in the webhook
- Its **allocations** (especially after invoice or receipt issued events — auto-allocation may have
  run)
- Any **corrective** or **credit** documents linked to that invoice

## When a refund is reversed

When a refund never reaches the guest, Lavanda issues a refund reversal note and sends:

| Webhook                                    | What it signals                                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `v2.invoicing.refund_reversal_note.issued` | A refund reversal note was issued, cancelling a refund note whose refund never reached the guest |

The payload has the same shape as `v2.invoicing.refund_note.issued` (document ID and workspace ID).
When you receive it, refresh:

- the refund reversal note, which tells you the refund note it reverses;
- that **refund note**, now Reversed;
- the original **receipt**, whose balance and status have changed;
- the allocations on all three.

You'll also get `v2.invoicing.allocation.deleted` for the refund note's link to the receipt, and
`v2.invoicing.allocation.created` for the refund reversal note's link to the refund note. No
separate receipt event is sent: use the refund reversal note event as your signal.

## Payment and payment method events

| Event                                | When it fires                                                        | What to query                       |
| ------------------------------------ | -------------------------------------------------------------------- | ----------------------------------- |
| `v1.payments.payment_method.created` | A card or Direct Debit mandate is saved on a booking                  | The payment method, by `booking.id` |
| `v1.payments.payment_method.updated` | The mandate's status or its card or bank details change               | The payment method, by `booking.id` |
| `v2.payments.payment.created`        | A payment is created, including a BACS collection from a mandate      | The payment, by `workspace.id`      |
| `v2.payments.payment.updated`        | A payment succeeds, fails, is cancelled, is disputed, or a dispute is won or lost | The payment, by `workspace.id` |
| `v2.payments.payment.deleted`        | A payment is removed                                                  | —                                   |

- Subscribe your endpoint to `v1.payments.payment_method.created` and `.updated` to receive mandate
  updates. An endpoint subscribed only to `payment.*` events does not receive them.
- Webhooks can arrive out of order. Order `payment_method` deliveries by `timestamp`.
- Values the API doesn't recognise yet come back as `UNKNOWN`.

Queries, fields and states: [Payments and payment methods](/finance-and-accounting/integrations/ar-payments-api/payments-and-payment-methods/).

## Recommended handling

- Subscribe to the events relevant to your integration.
- On every webhook: take the ID, query the AR API, then update your system.
- For booking-level reporting, consider refreshing all documents on that booking after major events.

Postman collection for example AR API queries:
<https://www.postman.com/lavanda/lavanda-external-api/overview>