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_hashandqr_urlfor audit trail. - Embed the QR code (
qr_base64) in the customer's PDF if needed.
Recommended actions on ACCEPTED_WITH_ERRORS:
- Store
invoice_hashandqr_urlfor 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_codeanderror_messageand tell the user.
Recommended actions on REJECTED:
- Alert the user — they need to correct and resubmit the invoice.
- Log
error_codeanderror_messagefor debugging.
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" | "email_domain.verified" | "email_domain.failed" | "email_domain.removed" | "connection.connected" | "connection.disconnected" | "invoice.reply.received" | "invoice.reply.deleted" | "invoice.email.bounced"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"verifactu.status.updated"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 verifactu.status.updated events.
Response Body
Invoice reply deleted
Delivered once when the company deletes a reply, usually to answer an erasure request. Only to the endpoints of the account that owns the company. It carries identifiers only. **Recommended actions:** - Erase what you stored about the reply from earlier `invoice.reply.*` events. - Discard an `invoice.reply.received` with the same `reply_id` that arrives after it. BeeL. stops sending it once the reply is deleted, but a retry already scheduled can still arrive. **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.**