Recibir los datos de tus contactos en tu sistema

Qué vas a lograr

Que cada vez que una persona complete tu bot, tu sistema (CRM, hoja de cálculo, automatización) reciba sus datos de forma segura.

Antes de empezar

• Una dirección https de tu sistema que reciba datos por POST (por ejemplo, un webhook de tu CRM o de una automatización). No funcionan direcciones http, ni IP numéricas, ni puertos distintos del 443.
• El secreto de firma que te entrega nuestro equipo (empieza por abs_). Guárdalo en tu gestor de contraseñas. No lo compartas ni lo pegues en correos o chats.

Cómo llegan los datos

Un POST con Content-Type: application/json y esta cabecera de seguridad: X-Archie-Firma: t=<segundos>,v1=<firma>. El cuerpo es así:

{ “evento”: “bot.webhook”, “id”: “…”, “conversacion_id”: “…”, “nodo”: “enviar”, “campos”: { “nombre”: “Ana”, “correo”: “ana@ejemplo.com” } }

Verificar que el mensaje es nuestro (recomendado)

1. Toma el valor t y el cuerpo exacto de la petición, tal cual llegó.
2. Calcula HMAC-SHA256 con tu secreto sobre el texto t + “.” + cuerpo y conviértelo a hexadecimal.
3. Compáralo con el valor v1 de la cabecera (compara en tiempo constante).
4. Rechaza el mensaje si t tiene más de 5 minutos.

Ejemplo de código:

import { createHmac, timingSafeEqual } from ‘node:crypto’;

function esValido(secreto, cuerpoCrudo, cabecera) {

const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(cabecera ?? ”);

if (!m || Math.abs(Date.now() / 1000 – Number(m[1])) > 300) return false;

const esperado = createHmac(‘sha256’, secreto).update(`${m[1]}.${cuerpoCrudo}`).digest();

return timingSafeEqual(esperado, Buffer.from(m[2], ‘hex’));

}

Qué responder

Responde con un código 2xx (200) lo antes posible, en menos de 5 segundos. Cualquier otra respuesta se toma como fallo y el bot sigue por su camino de error (por ejemplo, avisar a la persona que alguien la contactará). Por ahora enviamos un solo intento.

Problemas frecuentes

Cuándo escribirnos

Si seguiste estos pasos y no llegan datos, envíanos la dirección configurada y la hora aproximada. Nunca nos envíes el secreto.