n8n

Para qué sirve

n8n es una herramienta de automatización que se puede usar en su nube o instalar en un servidor propio. A diferencia de Make, permite escribir un trozo de código en un nodo, y por eso es la opción para verificar la firma de cada aviso antes de confiar en él.

Esta guía arma un flujo con el evento inmobiliaria.consulta.recibida («Consulta recibida»), cuyos datos son consulta_id, sobre y canal, y que termina en una fila de Google Sheets. Cualquier otro evento de Webhooks se arma igual.

Qué necesitás

• Una instancia de n8n con dirección pública en https. La nube de n8n la trae; si la instalás vos, el servidor tiene que ser alcanzable desde internet.
• Una cuenta de Kaptativa con API y MCP activo y permiso para crear destinos de webhook.
• Un token de Solo ver para el paso de la API, de Administración > API y MCP con Crear el token. Empieza con kpt_; acá lo escribimos kpt_....

Pasos

1. El nodo Webhook

1. En n8n, creá un flujo nuevo con Create workflow y agregá el nodo Webhook como primer paso.
2. Configuralo así: HTTP Method en POST, Path en kaptativa-consultas, Authentication en None (la autenticación es la firma, que verificás más abajo) y Respond en Immediately, para contestar 200 enseguida.
3. Tocá Add option, elegí Raw Body y activalo. Este paso es imprescindible: la firma se calcula sobre el texto original, y sin esto n8n entrega el cuerpo ya separado en campos.
4. El nodo muestra dos direcciones: Test URL y Production URL. Para probar usás la de test; para dejarlo andando, la de producción. Copiá la de test por ahora.

2. Registrar la dirección en Kaptativa

1. En el panel, abrí Administración > API y MCP y tocá Webhooks.
2. En Agregar un destino, ponele un nombre, pegá la dirección y elegí el evento inmobiliaria.consulta.recibida. Tocá Agregar el destino.
3. Copiá el secreto de firma (whsec_...): se muestra una sola vez. En n8n, guardalo como variable de entorno KAPTATIVA_WEBHOOK_SECRETO. Si tu plan de n8n trae Variables (Settings > Variables), también podés cargarlo ahí y leerlo como $vars.KAPTATIVA_WEBHOOK_SECRETO en lugar de $env.
4. En n8n, tocá Listen for test event en el nodo Webhook y, en Kaptativa, tocá Probar en el destino. El aviso llega como un evento webhook.prueba.

3. El nodo de código que verifica la firma

1. Agregá, a continuación del Webhook, un nodo Code. En Mode elegí Run Once for All Items y en Language, JavaScript.
2. Pegá este código. Es el mismo de Verificar la firma, con el import cambiado por require y la lectura del cuerpo crudo al final.

const { createHmac, timingSafeEqual } = require("crypto");

// cuerpo: el texto crudo del pedido, sin volver a armarlo. secreto: el whsec_ del destino
function firmaValida(encabezados, cuerpo, secreto) {
  const id = encabezados["webhook-id"];
  const momento = encabezados["webhook-timestamp"];
  const firmas = encabezados["webhook-signature"] ?? "";
  // Un aviso de hace más de cinco minutos no se acepta
  if (!id || !momento || Math.abs(Date.now() / 1000 - Number(momento)) > 300) return false;
  // La clave son los bytes del secreto: lo que viene después de whsec_, decodificado de base64
  const clave = Buffer.from(secreto.replace(/^whsec_/, ""), "base64");
  const esperada = createHmac("sha256", clave).update(`${id}.${momento}.${cuerpo}`).digest();
  // Puede venir más de una firma, separadas por espacios: alcanza con que una coincida
  return firmas.split(" ").some((f) => {
    const recibida = Buffer.from(f.replace(/^v1,/, ""), "base64");
    return recibida.length === esperada.length && timingSafeEqual(recibida, esperada);
  });
}

// El texto crudo del pedido: el nodo Webhook lo guarda como archivo (propiedad "data") cuando Raw Body está activo
const crudo = (await this.helpers.getBinaryDataBuffer(0, "data")).toString("utf8");
const encabezados = $input.first().json.headers;
// El secreto whsec_ del destino. Mejor en una variable de entorno de n8n; si tu n8n no deja leerlas, pegalo acá
const secreto = $env.KAPTATIVA_WEBHOOK_SECRETO;

const valido = firmaValida(encabezados, crudo, secreto);
// Si la firma no coincide, no se pasa nada: el flujo sigue solo con { valido: false }
return [{ json: valido ? { valido, id: encabezados["webhook-id"], evento: JSON.parse(crudo) } : { valido } }];

4. Cortar si la firma no coincide

1. Agregá un nodo If. En Conditions, elegí el campo valido como booleano, is true.
2. Seguí el flujo por la salida true. La salida false la dejás sin conectar o la mandás a un nodo Stop and Error con el mensaje «Aviso con firma inválida»: así queda registrado en las ejecuciones.
3. Para descartar repetidos, guardá el id (que es el webhook-id del aviso) de lo que ya procesaste, por ejemplo en una hoja aparte o con el nodo Remove Duplicates de n8n, usando id como clave.

5. Llamar a la API con el nodo HTTP Request

Si querés sumar datos que el aviso no trae, agregá un nodo HTTP Request:

Con curl:

curl "https://panel.kaptativa.app/api/v1/inmobiliaria/consultas?estado=abiertas&limite=25" \
  -H "Authorization: Bearer kpt_..."

La respuesta tiene datos (una entrada por consulta: numero, persona, propiedad, canal, estado, asesor, demorada, mensaje) y paginacion, con siguiente para pedir la página que sigue (Paginación). Igual que con Make: la API no busca una consulta por el consulta_id del aviso; sirve para traer las abiertas. El límite es de 120 pedidos por minuto por token (Límites de uso), y las operaciones que cambian algo piden Idempotency-Key (Idempotencia).

6. Terminar en Google Sheets y activar

1. Agregá el nodo Google Sheets con la operación Append Row. Conectá tu cuenta de Google con Create new credential si es la primera vez.
2. Elegí la planilla y la hoja. En las columnas, arrastrá evento.datos.consulta_id, evento.datos.sobre, evento.datos.canal y evento.creado.
3. Pasá la dirección al destino de Kaptativa: copiá la Production URL del nodo Webhook y, en el panel, tocá Editar en el destino, cambiá la dirección y guardá.
4. Arriba a la derecha de n8n, activá el flujo con el interruptor Active (en las versiones nuevas, Publish). Un flujo sin activar no recibe nada en la dirección de producción.

Cómo comprobar que anda

1. Con el flujo activo, tocá Probar en el destino de Kaptativa.
2. En n8n, abrí Executions: tiene que haber una ejecución correcta, con el nodo If yendo por true.
3. En Kaptativa, mirá el Registro de entregas del destino (con Actualizar): Entregada, código 200.
4. Para ver que la verificación sirve, mandá un POST a mano a la dirección de producción con un cuerpo cualquiera y sin firma: el flujo tiene que cortar en false.

Problemas comunes

Para usarlo con cuidado

• El secreto de firma y el token son contraseñas: variables o credenciales de n8n, nunca en una nota del flujo ni en una captura.
• Dale al flujo un token de Solo ver si solo lee. Si algún día tiene que cambiar algo, un token aparte, con escritura solo en ese módulo.
• Un aviso puede llegar repetido o fuera de orden: descartá por id y, si el orden importa, pedí el estado actual a la API.