Invoice issued
Delivered when an invoice is finalized and issued to the customer.
Trigger: Invoice transitions to its issued state (after validation and numbering).
Recommended actions:
- Update your own invoice mirror / accounting system.
- Trigger downstream automations (CRM, customer notifications, etc.).
Always verify BeeL-Signature before processing.
Header Parameters
HMAC-SHA256 signature. Format: t=<unix_timestamp>,v1=<hex_signature>
Verify this before processing any event (see spec description for algorithm).
^t=\d+,v1=[0-9a-f]{64}$Canonical event type identifier (matches the type field of the payload).
"verifactu.status.updated" | "invoice.issued" | "invoice.email.sent" | "invoice.pdf.generated" | "invoice.voided" | "recurring_invoice.paused" | "invoice.schedule_failed" | "account.claimed" | "company.created" | "representation.signed"UUID of the logical webhook event. Identical across all retry attempts.
Matches the id field in the payload. Use this for idempotency deduplication.
uuidUUID of this specific delivery attempt. Unique per HTTP call, even for retries of the same event. Use this to correlate with delivery logs in the BeeL. dashboard.
uuidSame value as BeeL-Event-Id. Standard idempotency header for deduplication.
uuidUnique identifier of this webhook event delivery.
uuid"invoice.issued"ISO-8601 timestamp when the event was created.
date-timeBeeL. API version that generated this event.
Deprecated in favour of the TEST/PROD environment vocabulary: livemode: true is equivalent to environment PROD.
true only for test deliveries triggered manually from the BeeL. dashboard.
Unique identifier (UUID) of the company the event is about, or null when not scoped to a specific company. A single endpoint receives events for every company it manages (multi-NIF / accounting firms); route on this field.
uuidNIF of the company the event is about (human-readable identifier).
Account the event happened in. For your own events this is your account; for events of accounts you manage it identifies which one. Route on this field together with account_external_ref.
uuidYour own identifier for that account, as supplied when you provisioned it (external_ref). Lets you map the event onto your internal record without an extra lookup. null for accounts you did not provision.
How account_id relates to you: own when the event happened in your own account, managed when it happened in an account you manage. Same field name and vocabulary as the account_relationship you set on POST /v1/webhooks to choose which of these you receive (own by default; all there means both).
"own" | "managed" | nullPayload for invoice.issued events.
Response Body
Invoice email sent
Delivered when an invoice has been successfully sent to its recipients via email. **Trigger:** Outbound email provider confirms the message was queued/delivered. **Recommended actions:** - Mark the invoice as "sent" in your records. - Persist `all_recipients` and `sent_at` for audit / customer service. **Always verify `BeeL-Signature` before processing.**
Invoice PDF generated
Delivered when BeeL. stores the PDF of an invoice. **Trigger:** - **Issued invoice:** once. The PDF of an issued invoice is generated a single time — with its VeriFactu QR when the issuer uses VeriFactu, at issuance otherwise — and is never modified afterwards. Voiding the invoice or issuing a corrective for it does **not** produce a new PDF and does not deliver this event: the status is reported by the API and by `invoice.voided`, not by the document. - **Proforma:** each time its PDF is generated (created, or regenerated after an edit). - **Exceptional regeneration:** BeeL. staff may regenerate the PDF of an issued invoice to fix a rendering defect. That is recorded and delivers the event again, with the next `data.generation`. It never sends an email to the customer. `data.generation` numbers the stored PDF of that invoice (`1`, `2`, …). Each generation is delivered once: a redelivery of the same generation is a retry, not a new PDF, and carries the same `BeeL-Event-Id`. **Recommended actions:** - Re-fetch the PDF with `GET /v1/companies/{company_id}/invoices/{invoice_id}/pdf`, which returns a fresh pre-signed URL. That call now waits for the PDF instead of making you poll, so a `200` is the normal answer. - Drop any copy you cached from an earlier delivery of this same invoice. **No URL travels in the payload** — on purpose. A download URL expires in five minutes and webhooks are retried for longer than that, so a delivered URL would often be dead on arrival and, until then, sitting in your logs. **Always verify `BeeL-Signature` before processing.**