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.

All field names use snake_case — both in the envelope and in data payloads.

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):

{
  "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.

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.

Available events

Event type	Delivered when	Resource
`account.claimed`	Delivered when an account holder you provisioned activates their credentials (sets a password and takes ownership of the account).	Account
`company.created`	Delivered when an account holder you provisioned registers their first (or an additional) NIF (company) during onboarding.	Company (NIF)
`invoice.email.sent`	Delivered when an invoice has been successfully sent to its recipients via email.	Invoice
`invoice.issued`	Delivered when an invoice is finalized and issued to the customer.	Invoice
`invoice.pdf.generated`	Delivered when BeeL. stores the PDF of an invoice.	Invoice
`invoice.schedule_failed`	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`	Delivered when an invoice is voided.	Invoice
`recurring_invoice.paused`	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`	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`	Delivered whenever the VeriFactu registration status of an invoice changes, starting with `PENDING` when the record is submitted.	Invoice

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.

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, and the one you must act on, BeeL-Signature, is covered in 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:

{
  "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.