⚠️ AVISO: Los webhooks están disponibles en los planes Avanzado y Total.

Los webhooks te permiten recibir notificaciones automáticas en tu servidor cada vez que ocurre algo relevante en FacturaDirecta: una factura creada, un contacto modificado, un gasto archivado... En lugar de consultar la API repetidamente para comprobar si hay cambios, los webhooks envían la información directamente a tu sistema en el momento en que se produce.

Son ideales para integraciones con ERPs, CRMs, plataformas de e-commerce, asesorías y cualquier automatización que necesite reaccionar a eventos de tu cuenta de facturación.

💡 Recomendación: Antes de configurar webhooks en producción, te recomendamos crear un entorno de pruebas (sandbox) para hacer tus primeras pruebas sin afectar tus datos reales.

Cómo funcionan

Configurar webhooks es un proceso sencillo en tres pasos:

Crea un endpoint: indica la URL HTTPS de tu servidor donde quieres recibir las notificaciones
Selecciona los eventos: elige qué tipos de evento quieres recibir (por ejemplo, solo facturas creadas o todos los eventos de contactos)
Recibe notificaciones: cada vez que ocurra uno de los eventos seleccionados, FacturaDirecta enviará un POST con los datos del evento a tu URL

Puedes crear varios endpoints para diferentes sistemas o propósitos, y cada uno puede suscribirse a eventos distintos.

Eventos disponibles

Los eventos se organizan por tipo de documento. Cada evento se identifica con el formato entidad.acción.

Facturas

Evento	Descripción
`invoice.created`	Factura creada
`invoice.updated`	Factura modificada
`invoice.archived`	Factura archivada
`invoice.unarchived`	Factura desarchivada
`invoice.sent`	Factura enviada por e-mail
`invoice.voided`	Factura anulada
`invoice.verifactu_sent`	Factura enviada a VeriFactu

Gastos

Evento	Descripción
`expense.created`	Gasto creado
`expense.updated`	Gasto modificado
`expense.archived`	Gasto archivado
`expense.unarchived`	Gasto desarchivado

Contactos

Evento	Descripción
`contact.created`	Contacto creado
`contact.updated`	Contacto modificado
`contact.archived`	Contacto archivado
`contact.unarchived`	Contacto desarchivado

Presupuestos

Evento	Descripción
`estimate.created`	Presupuesto creado
`estimate.updated`	Presupuesto modificado
`estimate.archived`	Presupuesto archivado
`estimate.unarchived`	Presupuesto desarchivado

Albaranes

Evento	Descripción
`delivery_note.created`	Albarán creado
`delivery_note.updated`	Albarán modificado
`delivery_note.archived`	Albarán archivado
`delivery_note.unarchived`	Albarán desarchivado

Transacciones

Evento	Descripción
`transaction.created`	Transacción creada
`transaction.updated`	Transacción modificada
`transaction.archived`	Transacción archivada
`transaction.unarchived`	Transacción desarchivada

Productos

Evento	Descripción
`product.created`	Producto creado
`product.updated`	Producto modificado
`product.archived`	Producto archivado
`product.unarchived`	Producto desarchivado

VeriFactu

Evento	Descripción
`verifactu_batch.sent`	Lote de facturas enviado a la AEAT

Estructura del evento

Cada vez que se dispara un evento, FacturaDirecta envía una petición POST a tu endpoint con un payload JSON como este:

{
  "id": "whe_550e8400-e29b-41d4-a716-446655440000",
  "type": "invoice.created",
  "object_type": "invoice",
  "created": 1709312400,
  "livemode": true,
  "company_id": "com_abc123",
  "data": {
    "object": { ... },
    "previous_attributes": { }
  }
}

Campo	Tipo	Descripción
`id`	string	ID único del evento (formato `whe_<uuid>`)
`type`	string	Tipo de evento (ej: `invoice.created`)
`object_type`	string \| null	Tipo del documento (ej: `invoice`, `contact`)
`created`	number	Fecha del evento en formato Unix timestamp (segundos)
`livemode`	boolean	`true` en producción, `false` en sandbox
`company_id`	string	Identificador de la empresa
`data.object`	object	Snapshot completo del documento en el momento del evento
`data.previous_attributes`	object	Solo en eventos `.updated`: campos modificados con sus valores anteriores

Nota: El payload captura el estado exacto del documento en el momento del evento. No se regenera desde el estado actual, lo que garantiza coherencia incluso si el documento cambia después.

Entrega y reintentos

FacturaDirecta se encarga de entregar cada evento de forma fiable:

Reintentos automáticos: si tu servidor no responde con un código HTTP 2xx, el sistema reintenta hasta 8 veces con intervalos crecientes (backoff exponencial)
Timeout: cada intento espera un máximo de 30 segundos a recibir respuesta
Desactivación automática: si un endpoint acumula 10 fallos consecutivos, se desactiva automáticamente para evitar envíos innecesarios. Puedes reactivarlo en cualquier momento desde el panel
HTTP 410 Gone: si tu servidor responde con un 410, el endpoint se desactiva inmediatamente sin reintentos. Útil cuando ya no quieres recibir notificaciones en esa URL

Seguridad

Cada evento que FacturaDirecta envía incluye una firma digital HMAC SHA256 en las cabeceras HTTP. Esto te permite verificar que la notificación proviene realmente de FacturaDirecta y que no ha sido manipulada.

👉 Consulta el artículo "Verificar la firma de webhooks" para ver cómo implementar la verificación en tu servidor con ejemplos de código en Node.js, Python y PHP.

Entornos sandbox y producción

Los webhooks mantienen una separación total entre entornos:

Los endpoints creados desde una empresa sandbox solo reciben eventos del sandbox (con livemode: false)
Los endpoints creados desde una empresa real solo reciben eventos de producción (con livemode: true)

Un endpoint sandbox nunca recibe eventos de producción y viceversa.

Siguientes pasos

Cómo configurar webhooks: guía paso a paso para crear y gestionar endpoints desde el panel de FacturaDirecta
Verificar la firma de webhooks: cómo comprobar que las notificaciones provienen de FacturaDirecta (con ejemplos de código)
API: Webhooks (endpoints y eventos): referencia completa de la API para gestionar webhooks por código

Webhooks: recibe notificaciones en tiempo real