# Invoice webhooks

Receive webhook notifications whenever invoices are finalized or canceled. Invoice webhooks can be used to trigger actions in your application whenever an invoice is changed, for example to keep an external invoicing or accounting system up to date.

## Events[​](#events "Direct link to Events")

| Event               | Description                                 |
| ------------------- | ------------------------------------------- |
| `invoice.finalized` | Occurs whenever a new invoice is finalized. |
| `invoice.canceled`  | Occurs whenever an invoice is canceled.     |

info

When an invoice is canceled, a webhook for the original invoice is triggered with the `invoice.canceled` event and the payload includes `canceled_at` and `cancellation_invoice_id`. We do NOT send a separate webhook for the cancellation invoice itself.

## Example Payload[​](#example-payload "Direct link to Example Payload")

We return JSON-formatted content with the following structure.

| Name    | Example content                                                                          | Description                                                |
| ------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `id`    | `a19e6168-3863-42a4-9454-48a2737d4ece`                                                   | UUID of the trigger resource                               |
| `type`  | `invoice`                                                                                | Resource type                                              |
| `event` | `invoice.finalized`                                                                      | Event that triggered the webhook, lowercase, dot-separated |
| `url`   | `https://app.freispace.com/invoicing/invoices/a19e6168-3863-42a4-9454-48a2737d4ece/view` | URL to the updated resource                                |
| `data`  | `{}`                                                                                     | The invoice's information                                  |

```
{

    "id": "a19e6168-3863-42a4-9454-48a2737d4ece",

    "type": "invoice",

    "event": "invoice.finalized",

    "url": "https://app.freispace.com/invoicing/invoices/a19e6168-3863-42a4-9454-48a2737d4ece/view",

    "data": {

        "id": "a19e6168-3863-42a4-9454-48a2737d4ece",

        "number": "IN-26-1003",

        "date": "2026-04-24",

        "due_date": "2026-05-24", // nullable

        "due_days": 30, // nullable

        "subject": "Invoice IN-26-1003",

        "service_period_from": null,

        "service_period_to": null,

        "order": {

            "id": "a19e6172-0225-40cc-b453-a14e685412a0",

            "number": "OR-1000"

        }, // nullable

        "cost_center": null,

        "issuer": {

            "id": "a19e5d30-a5e8-4e0a-863f-505ed95980cf",

            "name": "Post House"

        },

        "recipient": {

            "client_id": "a19d6036-bfe7-4976-878c-ebc9be05fd52",

            "client_address_id": "a19d6036-d2f3-47d3-85f9-278890d3e094",

            "client_contact_id": null,

            "address": "BBC One\n2nd Floor Egton Wing\nBBC Broadcasting House\nLONDON\nW1A 1AA"

        },

        "billing_email_addresses": [],

        "currency": "GBP",

        "total_sum_net": 32000, // in cents

        "total_sum_gross": 38400, // in cents

        "payment_due_at": "2026-05-24",

        "cancellation_invoice_id": null,

        "canceled_at": null // format: "2026-04-24T07:52:52+00:00" (UTC)

    }

}
```