NewThe SII in Live, under contract
BeeL
Get startedMulti-NIFVeriFactuSIIRulesStripeAPI referenceChangelog
Webhook Events

Compliance status of an invoice changed

Delivered when the standing of an invoice with one tax system changes: the status, system_status or stamps of one entry of its compliance. It is sent for every system, VeriFactu included, and carries that entry as it is after the change. A change that leaves the three as they were sends nothing.

verifactu.status.updated keeps being delivered for VeriFactu: subscribe to the one you use.

Recommended actions:

  • Route on compliance.type and branch on compliance.status; ignore a type you do not know.
  • On FULFILLED_NEEDS_FIX, or on REJECTED for VeriFactu, tell the user and read the submission with GET .../invoices/{invoice_id}/compliance-submissions for the reason.
  • On REJECTED for SII, you do not need to do anything: BeeL. sends it again and the reason is in error_code. If the customer's NIF or name is not in the AEAT census, sending it again leaves the status in FULFILLED_NEEDS_FIX. If the cause is in data that only you can correct, BeeL. contacts you.
  • Keep the stamps you need, for example to print them.

Always verify BeeL-Signature before processing.


Header Parameters

BeeL-Signaturestring

HMAC-SHA256 signature. Format: t=<unix_timestamp>,v1=<hex_signature>

Verify this before processing any event (see spec description for algorithm).

Match^t=\d+,v1=[0-9a-f]{64}$
BeeL-Eventstring

Canonical event type identifier (matches the type field of the payload).

Value in"verifactu.status.updated" | "invoice.compliance.updated" | "invoice.issued" | "invoice.email.sent" | "invoice.pdf.generated" | "invoice.voided" | "recurring_invoice.paused" | "invoice.schedule_failed" | "account.claimed" | "company.created" | "representation.signed" | "email_domain.verified" | "email_domain.failed" | "email_domain.removed" | "connection.connected" | "connection.disconnected" | "invoice.reply.received" | "invoice.reply.deleted" | "invoice.email.bounced"
BeeL-Event-Idstring

UUID of the logical webhook event. Identical across all retry attempts. Matches the id field in the payload. Use this for idempotency deduplication.

Formatuuid
BeeL-Delivery-Idstring

UUID 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.

Formatuuid
Idempotency-Keystring

Same value as BeeL-Event-Id. Standard idempotency header for deduplication.

Formatuuid
idstring

Unique identifier of this webhook event delivery.

Formatuuid
typestring
Value in"invoice.compliance.updated"
created_atstring

ISO-8601 timestamp when the event was created.

Formatdate-time
api_versionstring

BeeL. API version that generated this event.

livemodebooleanDeprecated

Deprecated in favour of the TEST/PROD environment vocabulary: livemode: true is equivalent to environment PROD.

test?boolean|null

true only for test deliveries triggered manually from the BeeL. dashboard.

company_id?string|null

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.

Formatuuid
nif?string|null

NIF of the company the event is about (human-readable identifier).

account_id?string|null

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.

Formatuuid
account_external_ref?string|null

Your 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.

account_relationship?string|null

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

Value in"own" | "managed" | null
data

Payload for invoice.compliance.updated events: the entry of the invoice's compliance that changed, as it is after the change. Same shape as in the Public API.

Response Body

VeriFactu registration status changed

Delivered whenever the VeriFactu registration status of an invoice changes, starting with `PENDING` when the record is submitted. **Trigger:** the record is submitted (`PENDING`), and then the AEAT answers it (usually within seconds to minutes). Sent when the public status changes (`new_status` differs from `previous_status`) and, while the status stays `REJECTED`, when the reason for the rejection changes (a different `error_code` or public `error_message`). See the `previous_status` property for when it is absent. A temporary AEAT server error keeps the record `PENDING` while BeeL. retries it, and sends no webhook. A technical problem on BeeL.'s side while submitting it also keeps it `PENDING` until BeeL. submits it again: it is not an outcome, so there is nothing to do. **Recommended actions on `ACCEPTED`:** - Store `invoice_hash` and `qr_url` for audit trail. - Embed the QR code (`qr_base64`) in the customer's PDF if needed. **Recommended actions on `ACCEPTED_WITH_ERRORS`:** - Store `invoice_hash` and `qr_url` for audit trail; the QR code (`qr_base64`) is valid too. - The record stands at the AEAT, but it also reported errors in it: review the data flagged in `error_code` and `error_message` and tell the user. **Recommended actions on `REJECTED`:** - Alert the user — they need to correct and resubmit the invoice. - Log `error_code` and `error_message` for debugging. **Always verify `BeeL-Signature` before processing.**

Fiscal 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. **Always verify `BeeL-Signature` before processing.**