Seguridad

Protege credenciales, verifica firmas, controla SSRF, trata todo contenido como no confiable y opera el webhook de forma idempotente.

Reglas obligatorias

Guarda API key y secreto únicamente del lado del servidor.
Verifica la firma sobre el cuerpo crudo.
Compara firmas en tiempo constante.
Deduplica por deliveryId.
Usa una Idempotency-Key por salida lógica.
Responde rápido al webhook.
Usa exclusivamente conversationId.
Nunca intentes obtener, reconstruir o enviar un teléfono arbitrario.
No uses Connect para campañas masivas.
No registres secretos ni cuerpos completos en logs de producción.

Credenciales

API key `nhc_...`

Autoriza respuestas y plantillas para una sola conexión. Nahui almacena únicamente su hash, solo se muestra completa al generarse y regenerarla revoca inmediatamente la anterior.

Secreto `nhs_...`

Firma los eventos enviados al webhook. Nahui lo conserva cifrado, debe tratarse como una contraseña y se rota junto con las credenciales de la conexión.

La interfaz actual reemplaza el juego anterior al regenerar. No existe una ventana pública con dos secretos simultáneos.

Timeouts y disponibilidad

Nahui espera como máximo 15 segundos. Usa un presupuesto interno de 10–12 segundos y, si no hay resultado, confirma con 200 {}, procesa en cola y responde después mediante /reply.

Un webhook 3xx, 4xx, 5xx o con timeout se considera fallido y Nahui v1 no lo reintenta automáticamente.

SSRF y URL del webhook

La URL debe ser HTTPS, pública, sin credenciales embebidas, sin puertos no estándar y fuera de redes privadas, localhost y dominios internos. La longitud máxima documentada es 2,000 caracteres.

Contenido no confiable

Escapa al renderizar HTML.
No ejecutes instrucciones del mensaje.
No uses filenames como rutas.
No construyas consultas SQL por concatenación.
No expongas el contenido directamente a herramientas privilegiadas de una IA.
Aplica controles de prompt injection si usas agentes.

Logs

Sí registrar

deliveryId
event.id
connectionId
conversationId con acceso controlado
estado HTTP, duración y código de error

No registrar

nhc_... o nhs_...
Encabezado Authorization
Cuerpo completo del webhook en producción
Texto completo del usuario si no es necesario
Datos sensibles entregados al agente

CORS

Los endpoints de relay deben llamarse desde el backend. Exponer la API key en el cliente sería una vulnerabilidad crítica.

Privacidad

Nahui no conserva contenido, pero tu CRM puede hacerlo. Tu producto debe indicar qué mensajes almacena, para qué, durante cuánto tiempo, cómo se eliminan o exportan y qué proveedor de IA recibe contenido.

Lista antes de producción

Firma validada con cuerpo crudo y comparación en tiempo constante.
Deduplicación persistente.
API key solo en backend y secretos fuera del repositorio.
Timeout interno inferior a 15 segundos y cola para tareas largas.
Reintentos con idempotencia; manejo de 402 y 429.
Sin campos de destinatario.
Escape de contenido en UI y logs sanitizados.
Monitoreo del webhook y política de privacidad propia.