# Events

All webhook event types and their payload schemas.

BeeL. sends webhook events when key things happen in your account. Each event has a `type` field that identifies what occurred, and a `data` object with event-specific details.

<Callout type="info">
  **All field names use `snake_case`** — both in the envelope and in `data` payloads.
</Callout>

## Envelope structure

Every webhook delivery follows the same envelope format (the `data` block depends on the event `type` — see each event's section below for the exact shape):

```json5
{
  "id": "3f7a1b2c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "type": "invoice.issued",
  "created_at": "2026-03-17T22:30:20.085Z",
  "api_version": "2025-01",
  "livemode": true,
  "company_id": "9f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "nif": "B12345674",
  "account_id": "4d6d8dca-689a-44f4-bafc-88fa8a1bc34b",
  "account_external_ref": "acct-2041",
  "account_relationship": "own",
  "data": { ... }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` (UUID) | Unique identifier for this webhook event. |
| `type` | `string` | Event type (see below). |
| `created_at` | `string` (ISO 8601) | Timestamp when the event was created. |
| `api_version` | `string` | API version used to generate the payload. |
| `livemode` | `boolean` | `true` for Live deliveries, `false` for Test. **Deprecated** in favour of the `PROD` / `TEST` environment vocabulary used elsewhere. |
| `test` | `boolean?` | `true` only for test deliveries. |
| `company_id` | `string` (UUID) \| `null` | Company (NIF profile) the event is about; `null` when not scoped to one. A single endpoint receives events for every company it manages — **route on this field**. |
| `nif` | `string` \| `null` | NIF of that company. |
| `account_id` | `string` (UUID) \| `null` | Account the event happened in. |
| `account_external_ref` | `string` \| `null` | Your own identifier for that account, as supplied when you provisioned it. `null` for accounts you did not provision. |
| `account_relationship` | `string` \| `null` | `own` or `managed` — how `account_id` relates to you. `null` when the event is not scoped to an account. |
| `data` | `object` | Event-specific payload (see below). |

Test payloads include an additional `"test": true` field.

<Callout type="info">
  **`account_relationship` is also how you subscribe.** A subscription's
  `account_relationship` (`own`, `managed` or `all`, default `own`) decides which
  accounts it receives events from — the same vocabulary you then route on. A
  *delivered* event is always `own` or `managed`, never `all`.
</Callout>

---

## Available events

| Event type | Delivered when | Resource |
|---|---|---|
| [`account.claimed`](/webhook-events/onAccountClaimed) | Delivered when an account holder you provisioned activates their credentials (sets a password and takes ownership of the account). | Account |
| [`company.created`](/webhook-events/onCompanyCreated) | Delivered when an account holder you provisioned registers their first (or an additional) NIF (company) during onboarding. | Company (NIF) |
| [`invoice.email.sent`](/webhook-events/onInvoiceEmailSent) | Delivered when an invoice has been successfully sent to its recipients via email. | Invoice |
| [`invoice.issued`](/webhook-events/onInvoiceIssued) | Delivered when an invoice is finalized and issued to the customer. | Invoice |
| [`invoice.pdf.generated`](/webhook-events/onInvoicePdfGenerated) | Delivered when BeeL. stores the PDF of an invoice. | Invoice |
| [`invoice.schedule_failed`](/webhook-events/onInvoiceScheduleFailed) | Delivered when an invoice you scheduled could **not** be issued on its date and BeeL. gave up retrying. The invoice is not lost: it stays in drafts, untouched, and can be issued by hand once the cause is fixed. | Invoice |
| [`invoice.voided`](/webhook-events/onInvoiceVoided) | Delivered when an invoice is voided. | Invoice |
| [`recurring_invoice.paused`](/webhook-events/onRecurringInvoicePaused) | Delivered when a recurring invoice (schedule) stops generating **without anyone asking for it** — a plan downgrade or an unattended generation that failed with something waiting will not fix. A schedule paused by a person is not delivered: whoever paused it already knows. | Recurring invoice |
| [`representation.signed`](/webhook-events/onRepresentationSigned) | Delivered when an account holder you provisioned signs the VeriFactu fiscal representation for one of their NIFs, enabling production invoicing on their behalf for that NIF. | Company (NIF) |
| [`verifactu.status.updated`](/webhook-events/onVeriFactuStatusUpdated) | Delivered whenever the VeriFactu registration status of an invoice changes, starting with `PENDING` when the record is submitted. | Invoice |

<Callout type="info">
  **`account.claimed`, `company.created` and `representation.signed` are
  provisioner-only**: they are delivered exclusively to the platform that provisioned the
  account, never to a subscription on any other account. See
  [Managed accounts](/multi-nif/managed-accounts).
</Callout>

Each event type links to its own page, generated from the webhook contract: the envelope,
the full `data` schema with which fields are required and which can be `null`, the trigger
and what to do when it arrives. Those pages are the reference — this guide covers what is
true of **every** delivery.

---

## Headers

Every delivery carries the same set of headers whatever the event type — they are
listed in [Overview](/webhooks#headers-sent-on-every-delivery), and the one you must act
on, `BeeL-Signature`, is covered in [Signatures](/webhooks/signatures).

---

## Environment isolation

Webhook subscriptions are isolated per environment:
- **Production** subscriptions only receive events from production invoices (`livemode: true`)
- **Sandbox** subscriptions only receive events from sandbox invoices (`livemode: false`)

---

## Test events

`POST /v1/accounts/{account_id}/webhooks/{webhook_id}/test` (or **Send test event** in the dashboard) fires a
synthetic payload. Its `type` is one of the event types the subscription listens to, and
it carries `"test": true` and a fixed message instead of real `data`:

```json
{
  "id": "c6b51d5a-b926-4b46-919e-ff3f68317967",
  "type": "invoice.issued",
  "created_at": "2026-09-24T07:24:58.585Z",
  "api_version": "2025-01",
  "livemode": false,
  "test": true,
  "data": {
    "message": "This is a test webhook from BeeL. Your endpoint is configured correctly."
  }
}
```

It is not about any company or account, so `company_id`, `nif`, `account_id` and
`account_relationship` are absent. A handler that routes on `company_id` should check
`test` first.

It is signed like any other delivery, so it also verifies your signature check. How to
fire it, and how it differs from a real delivery, is in
[Testing your endpoint](/webhooks#test-your-endpoint).

## Related

<Related>

- [Webhooks overview](/webhooks) — create a subscription
- [Signature verification](/webhooks/signatures) — verify each delivery
- [Deduplication](/webhooks/deduplication) — handle repeated deliveries

</Related>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi