Configurar webhooks

Los webhooks notifican en tiempo real cuando ocurren cambios en tu empresa: alguien crea una factura, se cobra una factura existente, se da de alta un contacto nuevo, etc. En vez de consultar la API periódicamente, configuras una URL HTTPS y FacturaDirecta envía una petición POST con el detalle del cambio cada vez que se produce un evento al que estás suscrito.

Esta página explica cómo configurarlos y operarlos desde el panel. Para la referencia técnica del payload, el catálogo completo de eventos y cómo verificar la firma en tu servidor, consulta el artículo de API: Webhooks.

Antes de empezar

Los webhooks forman parte de los planes que incluyen acceso a API. Si tu suscripción no lo permite, al intentar entrar a la sección verás un diálogo proponiéndote subir de plan.

Para configurarlos necesitas:

Una URL HTTPS accesible desde Internet. FacturaDirecta envía las peticiones desde nuestros servidores: ni los localhost ni las IPs privadas de tu red local funcionan.
Un servidor que reciba POST con cuerpo JSON en esa URL y responda con un código 2xx para confirmar la entrega.
Recomendado: lógica de verificación de firma en tu servidor (ver más abajo y el artículo de API).

Dónde están

Los webhooks tienen dos vistas complementarias dentro de la aplicación:

Endpoints — la configuración. Vive en Ajustes y desde aquí creas, editas y administras los endpoints de tu empresa. Toda la UI de gestión de endpoints (listado, crear, editar, rotar secret, enviar prueba, desactivar, eliminar, ver detalle) está en una pantalla integrada dentro de Ajustes.
Historial — la lista de eventos enviados a todos tus endpoints, con su estado y la respuesta de tu servidor. Es una página independiente accesible desde el botón Ver historial completo dentro del detalle de un endpoint.

Dentro del detalle de cada endpoint también verás un resumen del historial reciente de ese endpoint concreto.

Crear un endpoint

En la sección de webhooks en Ajustes, pulsa Crear endpoint. Si no tienes ninguno, verás el mensaje No tienes ningún endpoint configurado y el botón en pantalla.

Se abre el diálogo Nuevo endpoint con tres campos:

URL

Obligatoria. Debe empezar por https://. El texto de ayuda lo recuerda:

URL HTTPS a la que se enviarán los eventos

Si introduces una URL http://, al guardar verás el error:

La URL debe empezar por https://

Nombre

Opcional. Es un nombre libre para identificarlo en el listado cuando tengas varios endpoints (Producción, ERP interno, Staging, Webhook de Zapier, …). El texto de ayuda dice:

Nombre para identificar este endpoint

Eventos

La lista de tipos de evento a los que se suscribe este endpoint concreto. Encima de la lista verás el título Selecciona los eventos y dos accesos rápidos:

TODOS — marca todos los tipos de evento de un golpe. Útil para desarrollo y staging.
NINGUNO — desmarca todo, para empezar con la pizarra limpia.

El catálogo completo de tipos de evento (con su nombre exacto y descripción) vive en el artículo de API: Webhooks. Cada tipo sigue el formato <recurso>.<acción>: por ejemplo invoice.created, invoice.paid, contact.updated, webhook_endpoint.disabled.

Buena práctica: suscríbete solo a los eventos que tu integración consume. Suscribirse a tipos que ignoras genera ruido y carga innecesaria en tu servidor; suscribirse a más tipos no es más "completo".

Cuando termines, pulsa Guardar endpoint (o Cancelar para descartar el alta).

El signing secret: una sola vez

Inmediatamente después de crear el endpoint, FacturaDirecta abre un diálogo titulado Endpoint creado con un mensaje en grande:

Guarda ahora el signing secret en un lugar seguro. No se volverá a mostrar.

Debajo aparece el valor del Signing secret (una cadena alfanumérica larga) y un botón COPIAR para llevarlo al portapapeles. El secret se usa para verificar en tu servidor que cada petición que recibes viene realmente de FacturaDirecta y no de un tercero (ver "Verificar la firma" más abajo).

Cuando pulsas Cerrar el secret desaparece definitivamente. Si lo pierdes, la única forma de recuperarlo es rotarlo desde el menú de acciones del endpoint (lo describe la siguiente sección), pero rotar invalida el secret antiguo al instante: coordina el cambio en tu servidor antes de rotar.

Gestionar un endpoint existente

En el listado de endpoints, cada fila muestra URL, Nombre, Eventos, Estado y Último envío. Al pulsar sobre una fila se abre el diálogo Información del endpoint con los mismos datos en detalle y el menú Más acciones en la cabecera.

El menú contiene seis acciones, condicionadas por el estado actual:

Editar

Abre el diálogo Editar endpoint con los mismos tres campos del alta. Puedes cambiar URL, nombre o el conjunto de eventos suscritos. Pulsa Guardar endpoint para confirmar o Cancelar para descartar.

Rotar secret

Genera un signing secret nuevo y muestra el mismo diálogo Endpoint creado con el valor nuevo (cópialo antes de cerrarlo, exactamente igual que en el alta). Antes de hacerlo, una confirmación pregunta:

¿Estás seguro de que quieres rotar el secret? El secret actual dejará de funcionar inmediatamente.

Botones Sí, rotar y No. Como avisa el mensaje, el secret antiguo deja de validar peticiones desde el instante en que confirmas la rotación. Si tu servidor está validando contra el secret antiguo, las peticiones nuevas dejarán de superar la validación hasta que actualices el secret en tu servidor. Coordina el corte (despliegue del nuevo secret en tu lado → confirmación de la rotación aquí) para minimizar el hueco.

Enviar prueba

Solo aparece cuando el endpoint está Activo. Dispara inmediatamente un evento sintético de prueba contra tu URL y al recibir respuesta de tu servidor muestra el toast:

Evento de prueba enviado correctamente

Útil para validar que tu endpoint responde y para sembrar el historial con datos reales mientras integras.

Reactivar / Desactivar

Solo se ve una de las dos según el estado actual.

Desactivar (visible si el endpoint está activo). Pausa el envío de eventos. Confirmación:

¿Deseas desactivar este endpoint? No se enviarán nuevos eventos hasta que lo reactives. Botones: Sí, desactivar / No.
Reactivar (visible si el endpoint está desactivado). Vuelve a ponerlo en marcha. Si había eventos fallidos en cola del periodo anterior, se reencolan automáticamente y verás el toast:

Endpoint reactivado. Se han reencolado N eventos fallidos. donde N es el número concreto.

Eliminar

Borra el endpoint definitivamente. Confirmación:

¿Estás seguro de que quieres eliminar este endpoint?

Botones Sí, eliminar / No. No se puede deshacer; si eliminas por error, tendrás que crear uno nuevo (con su nuevo signing secret).

Estados de un endpoint

El chip de estado en el listado y en la cabecera del detalle puede tomar tres valores:

Activo (verde) — el endpoint está en marcha y los últimos envíos están funcionando con normalidad.
En alerta (naranja) — el endpoint está en marcha pero algunos envíos recientes a tu URL han fallado (timeouts, respuestas con status 5xx, etc.). Revisa el Historial del endpoint para ver qué está pasando: la columna HTTP y el detalle de cada evento te indican el motivo.
Desactivado (rojo) — el endpoint está pausado. No se le envía nada. Lo activas con la acción Reactivar.

Detalle del endpoint

Al abrir un endpoint, además de los datos básicos verás:

URL — la URL HTTPS configurada.
Estado — el chip mencionado arriba.
Nombre — si lo definiste al crear.
Eventos — los tipos a los que está suscrito, mostrados como chips uno por tipo.
Último envío — la fecha del último intento de entrega (si lo ha habido).

Debajo encontrarás el bloque Historial del endpoint: una tabla con los eventos más recientes enviados a esta URL. Columnas:

Columna	Significado
Tipo	El tipo de evento (`invoice.created`, etc.).
Estado	Resultado del envío (entregado / pendiente / fallido).
Fecha	Cuándo se intentó.
HTTP	Código HTTP que respondió tu servidor (en blanco si la petición ni siquiera llegó).

Si todavía no hay eventos para este endpoint verás:

No hay eventos recientes

Al pulsar sobre una fila se abre el detalle del evento concreto (ver sección siguiente).

Al final del bloque hay un enlace Ver historial completo que te lleva a la página /webhooks con un filtro preaplicado por la URL del endpoint actual.

El historial completo (página /webhooks)

La página Eventos de webhooks muestra todos los eventos enviados a todos los endpoints de tu empresa, con la potencia de un grid filtrable y exportable.

Columnas disponibles (puedes mostrar/ocultar y reordenar):

Columna	Significado
Fecha	Fecha y hora de creación del evento.
Tipo de evento	Tipo del evento (`invoice.created`, etc.).
Endpoint	Nombre del endpoint destino.
URL	URL del endpoint destino.
Estado	Pendiente / Entregado / Fallido / Deshabilitado.
HTTP	Último código HTTP recibido.
Intentos	Número de envíos realizados (≥ 1 si llega a entregar a la primera; aumenta con reintentos).
Entregado	Fecha del envío que tuvo éxito (si llegó a entregarse).

Filtros y búsqueda funcionan como en otras pantallas con grid (ventanas, listas de facturas, etc.). También puedes exportar las filas filtradas a CSV / Excel desde la barra del grid.

Al pulsar sobre una fila se abre el detalle del evento.

Detalle de un evento

El detalle de un evento muestra todo lo necesario para diagnosticar qué se envió y qué respondió tu servidor:

Fecha — cuándo se generó el evento.
HTTP — el código de la última respuesta de tu servidor (si hubo).
Payload — el cuerpo JSON exacto que se envió a tu URL. Es el mismo formato que documenta el artículo de API: Webhooks.
Respuesta — el cuerpo que respondió tu servidor (recortado a un tamaño razonable). Útil cuando tu servidor responde con un error legible.

Si el envío falló y quieres reintentarlo manualmente (por ejemplo, después de arreglar el problema en tu servidor), el botón Reenviar lo vuelve a encolar para entrega inmediata.

Restricciones técnicas

HTTPS obligatorio. Las URLs http:// se rechazan al guardar con el error La URL debe empezar por https://.
Sin IPs privadas. Por seguridad, las peticiones no se entregan a URLs que resuelvan a rangos privados (10.0.0.0/8, 192.168.0.0/16, 127.0.0.1, etc.). Si necesitas probar en local, expón tu servidor con un túnel HTTPS (tipo ngrok / Cloudflare Tunnel) y usa la URL pública resultante.
Reintentos automáticos en caso de fallo. Si tu servidor responde con un error o se cae, FacturaDirecta vuelve a intentar la entrega con backoff. Tras un número alto de fallos consecutivos el endpoint puede pasar a En alerta y, en última instancia, los eventos quedan como Fallido en el historial hasta que reactives o reintegres manualmente.

Verificar la firma

Cada POST que FacturaDirecta envía a tu URL incluye una firma HMAC calculada con el signing secret del endpoint. Verificarla en tu servidor es la garantía de que la petición es legítima, no ha sido manipulada en tránsito y proviene realmente de FacturaDirecta.

Los ejemplos de verificación en Node.js, Python y PHP están en el artículo de API: Webhooks (referencia técnica). Resumen del patrón:

Lee el body crudo (no parseado) de la petición.
Lee la cabecera HTTP con la firma que envía FacturaDirecta.
Calcula HMAC-SHA256(body_crudo, tu_signing_secret).
Compara contra la firma de la cabecera usando comparación timing-safe (no == ni ===).
Si no coinciden, responde HTTP 401 y descarta la petición.

Importante: si parseas el JSON antes de calcular la firma y calculas el hash sobre el JSON re-serializado, fallará. La firma se calcula sobre los bytes exactos del body recibido.

Recursos relacionados

API: Webhooks — referencia técnica completa: catálogo de eventos, forma del payload, formato exacto de la cabecera de firma y ejemplos completos en Node.js, Python y PHP.