NewRecurring invoices: `series_id` is optional
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Webhook Events

Email domain removed

Delivered when a sending domain of your account is removed. It is sent once per removal, only to the live endpoints of the account that owned the domain; the account that manages it does not receive it. The event belongs to the account, so company_id and nif are not set (absent or null).

Trigger: the domain is no longer in the account. reason says why: EXPIRED, DELETED_BY_USER or DELETED_AT_PROVIDER. The payload carries the domain as it was at removal and has no previous_status.

Recommended actions:

  • Stop treating the domain as available for sending. If is_default is true, the account's emails go out from BeeL until you set another default with setAccountEmailDomainDefault.
  • EXPIRED and DELETED_AT_PROVIDER: register the domain again with createAccountEmailDomain if you still want it. DELETED_BY_USER: none, unless the deletion was not intended.

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

Request Body

idstring

Unique identifier of this webhook event delivery.

Formatuuid
typestring
Value in"email_domain.removed"
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 email_domain.removed events: the email domain as it was when it was removed, and why.

Response Body

Email domain verification failed

Delivered when a sending domain of your account changes to `FAILED`. It is sent once per transition, only to the live endpoints of the account that owns the domain; the account that manages it does not receive it. The event belongs to the account, so `company_id` and `nif` are not set (absent or `null`). **Trigger:** the DNS records of the domain could not be verified. `previous_status` tells the two cases apart: `PENDING` means the domain never verified; `VERIFIED` means it was verified and stopped passing the check. **Recommended actions:** - Check that the records in `dns_records` are published exactly as shown, then request a new check with `verifyAccountEmailDomain`. - If `previous_status` is `PENDING`, do it before the domain is removed, 72 hours after it was registered. A domain that was once `VERIFIED` is not removed for that reason. - Until the domain is `VERIFIED` again, do not rely on it for sending. **Always verify `BeeL-Signature` before processing.**

Email domain verified

Delivered when a sending domain of your account changes to `VERIFIED`: its DNS records were detected and the domain can be used to send. It is sent once per transition, only to the live endpoints of the account that owns the domain; the account that manages it does not receive it. The event belongs to the account, so `company_id` and `nif` are not set (absent or `null`). **Trigger:** the DNS records of the domain were detected after you requested a check or on a later check. `previous_status` is `PENDING` or `FAILED`. **Recommended actions:** - Mark the domain as ready in your records. No further action is needed on the DNS records. **Always verify `BeeL-Signature` before processing.**