Webhook event delivery
Factuarea POSTs this body to every subscribed endpoint when a subscribed event occurs. The receiver verifies the Factuarea-Signature HMAC header and SHALL respond with a 2xx status to acknowledge the delivery. A 5xx, a timeout and the client errors 408, 425 and 429 are retried with exponential backoff until the attempts run out; any other 4xx ends the delivery for good, with no automatic retry.
Headers
Always application/json.
HMAC-SHA256 signature of the raw request body, used to verify the delivery is authentic. Format t=<timestamp>,v1=<signature>; while the previous secret of a rotation is still valid it carries a second v1 (t=<timestamp>,v1=<signature>,v1=<signature of the previous secret>), and the delivery is authentic when any of them matches.
Stable identifier of the event (UUID v7). Identical across redeliveries of the same event.
Type of the delivered event, e.g. invoice.paid.
Identifier of the delivery (UUID v7): one event sent to one endpoint. It stays the same across the automatic retries of that delivery and across a manual retry of an account endpoint; it changes when a company endpoint delivery is replayed (the replay creates a new delivery of the same event) and from one endpoint to another. To deduplicate, use Factuarea-Event-Id or Idempotency-Key, not this header.
Standard idempotency header. Its value is identical to Factuarea-Event-Id (the stable UUID v7 of the event), so a receiver can deduplicate redeliveries using the industry-standard header.
Payload
Example payload
{
"data": {
"object": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"object": "invoice",
"number": "FAC-2026-00042",
"is_number_assigned": true,
"type": "F1",
"series": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02",
"code": "FAC-2026"
},
"client": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
"name": "Acme Soluciones SL"
},
"status": "paid",
"price_list_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10",
"price_list_name": "Tarifa profesional 2026",
"issued_on": "2026-03-15",
"due_on": "2026-04-14",
"operation_on": null,
"subtotal": "1000.00",
"taxes_total": "210.00",
"total_vat": "210.00",
"total_retention": "0.00",
"total_surcharge": "0.00",
"total": "1210.00",
"total_disbursements": "0.00",
"total_to_pay": "1210.00",
"currency": "EUR",
"notes": "Servicios profesionales marzo 2026.",
"external_id": "ERP-2026-0042",
"lines": [
{
"object": "invoice_line",
"description": "Consultoría técnica (10 h)",
"additional_description": "Auditoría inicial e informe de mejoras",
"product": {
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03",
"name": "Consultoría técnica (hora)"
},
"quantity": 10,
"unit_price": "100.0000",
"tax_rate": 21,
"retention_rate": 0,
"surcharge_rate": 0,
"discount_percent": 0,
"subtotal": "1000.00",
"taxes": "210.00",
"total": "1210.00",
"variant": null,
"presentation": null,
"item_kind": "service",
"commercial_unit_code": "HUR",
"base_unit_code": "HUR",
"conversion_factor": "1.000000",
"base_quantity": "10.0000",
"counted_quantity": null,
"counted_unit": null,
"price_list_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10",
"price_list_name": "Tarifa profesional 2026",
"price_source": "price_list",
"price_unit_code": "HUR",
"configuration": null,
"options": [],
"price_semantics": "per_commercial_unit",
"price_adjustment_total": "0.0000",
"option_adjustments_absorbed": false,
"indirect_tax_regime": "iva",
"aeat_tax_code": "S1",
"line_type": "NORMAL"
}
],
"metadata": {
"order_id": "PO-2026-0042"
},
"tags": [
"consultoria",
"cliente-vip"
],
"custom_fields": [
{
"field": "centro_coste",
"value": "CC-2026-001"
},
{
"field": "numero_pedido",
"value": "PO-2026-0042"
}
],
"operation_regime": "general",
"exemption_reason": null,
"legal_mentions": [],
"exclude_347": false,
"verifactu_status": "accepted",
"paid_amount": "1210.00",
"pending_amount": "0.00",
"payments": {
"detail": [
{
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90",
"object": "payment",
"invoice_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"amount": "1210.00",
"payment_date": "2026-03-20",
"payment_method": "bank_transfer",
"payment_method_text": "Transferencia bancaria",
"reference": "TRF-2026-0042",
"notes": null,
"is_reversed": false,
"reversed_at": null,
"reversal_reason": null,
"reversal_reason_text": null,
"reversal_note": null,
"created_at": "2026-03-20T10:30:00Z",
"updated_at": "2026-03-20T10:30:00Z"
}
],
"total": "1210.00",
"pending": "0.00"
},
"is_corrective": false,
"corrective": null,
"payment": {
"method": "bank_transfer",
"reference": "TRF-2026-0042",
"date": "2026-03-20"
},
"public_link": {
"object": "public_link",
"url": "https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42",
"enabled": true,
"expires_at": "2026-09-15T23:59:59Z",
"max_days": 120
},
"substituted_by": null,
"recurring": null,
"paid_recorded_at": "2026-03-20T10:30:00Z",
"paid_date": "2026-03-20",
"issued_at": "2026-03-15T11:45:00Z",
"sent_at": "2026-03-15T11:47:12Z",
"sent_via": "email",
"is_sent": true,
"voided_at": null,
"void_reason": null,
"scheduled_for": null,
"scheduled_action": null,
"channel": null,
"source_store_id": null,
"origin": "native",
"created_at": "2026-03-15T11:30:00Z",
"updated_at": "2026-03-20T10:30:00Z"
}
}
}Response
The receiver acknowledged the delivery. Any 2xx status is treated as success; the body is ignored.
Changes
Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.