n8n webhook a Postgres: un ejemplo de despliegue en Lizard

Un webhook de n8n puede escribir JSON en Postgres y devolver la fila guardada en un único flujo de trabajo. Este ejemplo ejecuta n8n en Lizard, protege el webhook con una credencial de cabecera y usa un ID de petición para evitar filas duplicadas cuando el remitente reintenta.

El repositorio público incluye la imagen fijada, el flujo de trabajo, la definición de tabla y el script de comprobación. Este artículo cubre una única instancia de n8n y peticiones JSON. Para la configuración de alojamiento más amplia, empieza por Alojamiento de n8n en Lizard.

Qué ejecuta el ejemplo

El servicio n8n y su Managed Postgres dedicado se ejecutan en la misma región. Postgres almacena tanto los registros de flujo de trabajo y credenciales propios de n8n como la tabla webhook_events del ejemplo. La aplicación usa una instancia; en este ejemplo no hay cola Redis ni worker separado.

El repositorio fija n8n 2.38.5 y el digest de la imagen oficial. Un digest fijo hace que la elección de imagen sea reproducible. Revisa las versiones posteriores de n8n y prueba las actualizaciones antes de cambiar el fijado.

El flujo de trabajo tiene tres nodos:

1. Webhook acepta una petición POST de producción con una cabecera X-Example-Key.
2. Almacenar evento ejecuta una consulta Postgres parametrizada.
3. Responder devuelve el ID de petición guardado, el cuerpo JSON y la hora de creación.

Configurar la base de datos, el propietario y la URL pública

Crea un servicio desde el repositorio y un Managed Postgres por separado en el mismo proyecto de Lizard. Las instrucciones del repositorio listan los comandos y variables de entorno.

Establece DB_TYPE=postgresdb y vincula el host, puerto, nombre, usuario y contraseña de la base de datos a las variables del addon. Una base de datos ejecutándose junto a n8n no basta: n8n debe recibir esos valores y conectar correctamente. Consulta la configuración de Postgres de n8n.

Genera y guarda un N8N_ENCRYPTION_KEY aparte antes del primer inicio. n8n lo usa para proteger las credenciales almacenadas en su base de datos. Una clave aleatoria nueva en cada despliegue impediría a n8n leer las credenciales antiguas. Guarda la clave con tus registros de recuperación, fuera del repositorio.

El ejemplo también configura el propietario antes de que n8n sea accesible. Usa N8N_INSTANCE_OWNER_MANAGED_BY_ENV y un hash de contraseña bcrypt, siguiendo la configuración de propietario de n8n. La contraseña de acceso y la clave del webhook son secretos separados.

Establece N8N_HOST en el nombre de host público del servicio, sin esquema ni ruta. El script de inicio construye la URL HTTPS WEBHOOK_URL y la URL del editor a partir de ese nombre de host. Usa el puerto 5678. Revisa el ajuste proxy-hop si añades otro proxy delante de Lizard.

Importar y publicar el flujo de trabajo

Crea webhook_events con el archivo SQL del repositorio. Importa las credenciales de Postgres y de cabecera en n8n, luego importa el flujo de trabajo. El script de preparación de credenciales lee los valores secretos del entorno del servicio y escribe un archivo de importación privado temporal; el flujo de trabajo público contiene solo IDs y nombres de credenciales.

Usa el editor de n8n para publicar el flujo de trabajo, o usa n8n publish:workflow --id=lizardPostgresExample. La publicación por CLI cambia la base de datos; el proceso n8n en ejecución necesita un reinicio para registrar ese cambio. Este comportamiento está documentado en la guía de CLI de n8n.

Comprueba /healthz/readiness antes de enviar peticiones. La URL de producción usa /webhook/lizard-postgres-example. La URL /webhook-test/ pertenece a una sesión de prueba del editor y no sustituye a un flujo de trabajo publicado.

Enviar una petición y probar un reintento

Con la URL pública y la clave del webhook en variables de entorno:

curl --fail-with-body "$N8N_URL/webhook/lizard-postgres-example" \
  -H 'Content-Type: application/json' \
  -H "X-Example-Key: $EXAMPLE_WEBHOOK_TOKEN" \
  --data '{"requestId":"example-001","message":"hello"}'

La consulta SQL vincula el ID de petición y el cuerpo JSON como valores. No construye SQL uniendo la entrada del usuario en el texto de la consulta. Las comillas y el JSON anidado permanecen como datos.

La clave primaria de la tabla es request_id. En caso de conflicto, la consulta devuelve la primera fila guardada. Enviar el mismo ID con un mensaje distinto no cambia la carga original. Esa es la política de reintento de este ejemplo; elige otra política si tu aplicación necesita actualizaciones o errores de conflicto.

Usa un ID de petición nuevo para cada evento distinto. No reutilices un ID de prueba para representar un nuevo evento y esperar una segunda fila.

Comprobaciones de despliegue

El 9 de septiembre de 2026, ejecutamos n8n 2.38.5 con Postgres 18.6 en eu-west-lim-a. Las mismas siete comprobaciones pasaron antes y después de reiniciar el servicio n8n.

La base de datos conservó un evento tras ambas ejecuciones. El cuerpo JSON y la hora de creación coincidieron tras el reinicio. El cuerpo de prueba incluía comillas y JSON anidado. El propietario también accedió y encontró el flujo de trabajo importado en el editor.

Lee el registro de despliegue y resultados sin procesar. El registro nombra el commit de código probado. Ejecuta el script de comprobación del repositorio contra tu propio despliegue antes de usarlo para tus flujos de trabajo.

Qué no cubren estas comprobaciones

El ejemplo no prueba carga, tiempo de actividad, latencia de arranque en frío ni una factura mensual completa. No configura modo cola, copias de seguridad de base de datos, subidas de archivos ni recuperación ante pérdida de base de datos.

Una comprobación de reinicio de servicio establece que este despliegue puede leer sus flujos de trabajo y credenciales guardados tras reiniciar. No establece recuperación ante desastres. Para eso, haz una copia de seguridad de la base de datos, conserva la clave de cifrado, restaura en un entorno separado y vuelve a ejecutar el flujo de trabajo.

Este flujo de trabajo JSON no requiere un sistema de archivos local persistente. Los flujos de trabajo que leen o escriben archivos locales necesitan almacenamiento adecuado y sus propias pruebas de persistencia. Revisa Persistent Volumes y los requisitos de almacenamiento de n8n antes de añadir esa carga.

Preguntas frecuentes

¿Necesita n8n Postgres? No. n8n autoalojado puede usar SQLite. Este ejemplo usa Postgres para mantener los registros de flujo de trabajo, credenciales y ejecuciones fuera del contenedor de la aplicación y demostrar un flujo de trabajo que escribe en base de datos.

¿Por qué un webhook funciona en el editor pero devuelve 404 en otro sitio? Comprueba que el flujo de trabajo esté publicado y que el remitente use la ruta de producción /webhook/. Una publicación por CLI también requiere que el proceso n8n en ejecución se reinicie.

¿Qué debe mantenerse igual tras un redespiegue? La conexión a la base de datos debe apuntar a la base de datos prevista, y la clave de cifrado debe seguir pudiendo descifrar sus credenciales. Mantén estable la URL pública del webhook y el contrato de autenticación para los llamadores.

¿Es esta una configuración completa de n8n para producción? Es un ejemplo comprobado de instancia única. Añade copias de seguridad, monitorización, almacenamiento y un plan de capacidad para tu carga antes de depender de él para automatización en producción.