Volver al Blog
Red

Encabezados HTTP personalizados: controla los encabezados de las solicitudes con BotBrowser

Aprende a establecer encabezados HTTP personalizados a nivel del motor del navegador usando la bandera --bot-custom-headers de BotBrowser y el API CDP para una identidad de solicitud consistente.

Introducción

Los encabezados HTTP forman parte de cada solicitud que envía tu navegador. Encabezados como User-Agent, Accept-Language, Sec-CH-UA y Referer constituyen una parte importante de la identidad de red del navegador. Cuando estos encabezados no coinciden con tu perfil de huella, o cuando necesitas inyectar encabezados específicos de la aplicación para autenticación y enrutamiento, las APIs estándar del navegador se quedan cortas.

BotBrowser ofrece control de encabezados a nivel de motor mediante la bandera --bot-custom-headers y el comando CDP BotBrowser.setCustomHeaders. A diferencia de los enfoques basados en extensiones que interceptan solicitudes después de formarse, BotBrowser modifica los encabezados antes de que la solicitud salga de la pila de red del navegador, cubriendo todos los tipos de solicitud sin brechas temporales.

Impacto en la privacidad

Los encabezados HTTP revelan mucha información sobre tu entorno de navegador. La cadena User-Agent identifica la versión del navegador y el sistema operativo. Accept-Language revela las preferencias de idioma y, por extensión, la región geográfica probable. Los encabezados Client Hints (Sec-CH-UA, Sec-CH-UA-Platform, Sec-CH-UA-Mobile) proporcionan datos estructurados sobre la marca del navegador, la plataforma y el tipo de dispositivo.

Cuando estos encabezados no se alinean con otros aspectos de tu huella, la inconsistencia destaca. Un navegador que informe Accept-Language: de-DE pero tenga una zona horaria de EE. UU., o un Sec-CH-UA-Platform: "Windows" pero propiedades navigator específicas de macOS, crea desacuerdos que los sistemas de seguimiento pueden correlacionar.

Los perfiles de BotBrowser alinean automáticamente todos los encabezados estándar con la identidad del perfil. User-Agent, todos los Sec-CH-UA-* y Accept-Language se derivan de la configuración de navegador, plataforma y región del perfil. Los encabezados personalizados agregados mediante --bot-custom-headers amplían esta base sin interrumpir el conjunto estándar del perfil.

Antecedentes técnicos

Cómo los navegadores construyen los encabezados de solicitud

Cuando un navegador envía una solicitud HTTP, construye encabezados desde múltiples fuentes:

  1. Encabezados integrados: User-Agent, Accept, Accept-Encoding, Accept-Language son añadidos por el motor del navegador según configuraciones internas.
  2. Client Hints: Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform se envían por defecto. Los hints de alta entropía como Sec-CH-UA-Full-Version-List se envían solo cuando el servidor los solicita mediante Accept-CH.
  3. Encabezados de aplicación: Encabezados establecidos por JavaScript a través de fetch() o XMLHttpRequest.
  4. Encabezados inyectados por extensiones: Encabezados añadidos por extensiones mediante la API webRequest.

El orden y la composición de estos encabezados crean un patrón consistente para cada navegador. Chrome, Edge y Firefox producen ordenamientos y combinaciones distintas.

Consistencia basada en perfiles

Cuando BotBrowser carga un perfil de huella, configura todos los encabezados estándar para que coincidan con la identidad del perfil:

  • User-Agent coincide con la versión del navegador y la plataforma del perfil
  • Sec-CH-UA contiene los tokens de marca correctos en el orden adecuado
  • Sec-CH-UA-Platform coincide con el sistema operativo del perfil
  • Accept-Language refleja la configuración regional y preferencias de idioma del perfil

Estos encabezados se establecen a nivel de motor y se aplican a todas las solicitudes, incluida la solicitud de navegación inicial, cargas de subrecursos y solicitudes iniciadas por JavaScript. No existe una brecha temporal donde puedan observarse encabezados incorrectos.

Encabezados personalizados vs estándar

Los encabezados personalizados (por ejemplo, que comienzan con X- o nombres específicos de la aplicación) tienen un propósito distinto al de los encabezados estándar. Transportan datos específicos de la aplicación: tokens de autenticación, identificadores de sesión, marcadores de versión o pistas de enrutamiento. La bandera --bot-custom-headers de BotBrowser agrega estos encabezados sin modificar los encabezados estándar gestionados por el perfil.

Header Sources in BotBrowser Profile (Automatic) User-Agent, Sec-CH-UA-* Accept-Language CLI Override --bot-config-locale --bot-config-languages Custom Headers --bot-custom-headers BotBrowser.setCustomHeaders Final Request Headers All sources merge at the engine level before the request is sent

Enfoques comunes y sus limitaciones

Modificación de encabezados basada en extensiones

Las extensiones pueden modificar encabezados a través de webRequest.onBeforeSendHeaders. Esta aproximación tiene varios inconvenientes:

  • Problemas de timing: la primera solicitud de navegación puede dispararse antes de que el listener de la extensión esté registrado
  • Cobertura incompleta: solicitudes de service worker, preflight CORS y algunas solicitudes internas pueden no activar el listener
  • Artefactos detectables: extensiones que modifican encabezados dejan rastros en la superficie de la API de extensiones
  • Sobrecarga de rendimiento: cada solicitud pasa por el manejador JS de la extensión, agregando latencia

Anulaciones basadas en CDP

Puppeteer y Playwright ofrecen APIs de anulación de encabezados mediante CDP:

// Puppeteer - limited approach
await page.setExtraHTTPHeaders({ 'X-Custom': 'value' });

Funciona a nivel de página pero tiene limitaciones:

  • Los encabezados establecidos así solo aplican a la página específica
  • Service workers y shared workers pueden no recibir los encabezados personalizados
  • El comando CDP Network.setExtraHTTPHeaders requiere Network.enable, lo cual puede afectar el fingerprinting

Encabezados Fetch/XHR en JavaScript

Establecer encabezados en llamadas individuales de fetch() o XMLHttpRequest solo cubre solicitudes iniciadas por JavaScript. Navegación, cargas de imágenes, hojas de estilo y otras solicitudes del navegador no quedan cubiertas.

Enfoque de BotBrowser

La bandera --bot-custom-headers

La bandera --bot-custom-headers de BotBrowser (PRO) inyecta encabezados personalizados a nivel del motor del navegador:

chrome --bot-profile="/path/to/profile.enc" \
       --bot-custom-headers='{"X-Custom-Header":"value","X-Auth-Token":"abc123"}' \
       --user-data-dir="$(mktemp -d)"

Como la modificación ocurre dentro de la pila de red de Chromium, los encabezados personalizados se añaden a:

  • Solicitudes de navegación inicial
  • Subrecursos (imágenes, scripts, estilos, fuentes)
  • Solicitudes XHR y Fetch
  • Solicitudes de upgrade WebSocket
  • Solicitudes de Service Worker

No hay brechas temporales ni solicitudes omitidas.

Comando CDP BotBrowser.setCustomHeaders

Para la gestión en tiempo de ejecución, BotBrowser ofrece un comando CDP que se envía a la sesión a nivel de navegador:

Puppeteer:

const cdpSession = await browser.target().createCDPSession();
await cdpSession.send('BotBrowser.setCustomHeaders', {
  headers: { 'x-requested-with': 'com.example.app' }
});

Playwright:

const cdpSession = await browser.newBrowserCDPSession();
await cdpSession.send('BotBrowser.setCustomHeaders', {
  headers: { 'x-requested-with': 'com.example.app' }
});

Importante: este comando debe enviarse a la sesión CDP a nivel de navegador, no a la sesión de página. Enviarlo a un target de página retornará ProtocolError: 'BotBrowser.setCustomHeaders' wasn't found.

Configuración a nivel de perfil

Los encabezados personalizados también se pueden configurar en la configuración del perfil mediante configs.customHeaders. Esto es útil cuando deseas que los encabezados estén integrados en el perfil en lugar de especificarlos al iniciar.

Configuración y uso

Configuración CLI con encabezados personalizados

chrome --bot-profile="/path/to/profile.enc" \
       --bot-custom-headers='{"X-App-Version":"2.1.0","X-Session-ID":"sess_abc123"}' \
       --proxy-server=socks5://user:pass@proxy:1080 \
       --user-data-dir="$(mktemp -d)"

Integración con Playwright

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
      '--bot-custom-headers={"X-Auth":"token123","X-Client":"webapp"}',
    ],
    headless: true,
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

Integración con Puppeteer

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
      '--bot-custom-headers={"X-Auth":"token123"}',
    ],
    headless: true,
    defaultViewport: null,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

Citas en JavaScript

Al pasar --bot-custom-headers desde JavaScript, no incluyas comillas de shell dentro del valor:

// Correcto
const headers = { 'X-Custom': 'value', 'X-Auth': 'token' };
args.push('--bot-custom-headers=' + JSON.stringify(headers));

// Incorrecto - las comillas simples se convierten en parte del valor JSON
args.push(`--bot-custom-headers='${JSON.stringify(headers)}'`);

Actualizaciones en tiempo de ejecución vía CDP

Para flujos que necesiten cambiar encabezados durante la sesión:

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
    ],
    headless: true,
  });

  const cdpSession = await browser.newBrowserCDPSession();

  // Establecer encabezados iniciales
  await cdpSession.send('BotBrowser.setCustomHeaders', {
    headers: { 'x-requested-with': 'com.example.app' }
  });

  const page = await (await browser.newContext()).newPage();
  await page.goto('https://example.com');

  // Actualizar encabezados en la sesión
  await cdpSession.send('BotBrowser.setCustomHeaders', {
    headers: { 'x-requested-with': 'com.example.app', 'x-session': 'refreshed' }
  });

  await page.goto('https://example.com/dashboard');
  await browser.close();
})();

Verificación

Después de lanzar BotBrowser con encabezados personalizados, verifica que se apliquen:

  1. Abre una página que muestre los encabezados de solicitud (por ejemplo https://httpbin.org/headers)
  2. Confirma que tus encabezados personalizados aparecen en la respuesta
  3. Revisa la pestaña Network en DevTools para ver los encabezados en todos los tipos de solicitud
  4. Verifica que los encabezados estándar (User-Agent, Sec-CH-UA) aún coincidan con el perfil
const page = await context.newPage();
await page.goto('https://httpbin.org/headers');
const headersText = await page.textContent('body');
console.log('Request headers:', headersText);

Buenas prácticas

  1. Usa --bot-custom-headers para encabezados estáticos. Si los encabezados no cambian durante la sesión, la bandera CLI es más sencilla que CDP.

  2. Usa BotBrowser.setCustomHeaders para encabezados dinámicos. Para rotación de tokens u otros cambios en tiempo de ejecución, emplea el comando CDP.

  3. No sobrescribas encabezados gestionados por el perfil. Los encabezados personalizados deben añadir campos nuevos en lugar de reemplazar User-Agent o Sec-CH-UA.

  4. Evita nombres de encabezados comunes de extensiones. Encabezados como X-Forwarded-For o X-Real-IP pueden entrar en conflicto con infraestructuras de proxy; usa nombres específicos de la aplicación.

  5. Prueba con httpbin.org/headers. Este endpoint devuelve los encabezados recibidos, lo que facilita la verificación.

  6. Usa siempre la sesión CDP a nivel de navegador para setCustomHeaders. Las sesiones a nivel de página devolverán error.

Preguntas frecuentes

¿Los encabezados personalizados se aplican a todas las solicitudes o solo a la navegación? Se aplican a todas. BotBrowser añade encabezados personalizados a nivel de motor, cubriendo navegación, subrecursos, XHR, Fetch, WebSocket y Service Worker.

¿Puedo establecer encabezados personalizados distintos por contexto? La bandera --bot-custom-headers aplica a todos los contextos. Para encabezados por contexto, usa BotBrowser.setCustomHeaders y actualízalos entre operaciones de contexto.

¿Los encabezados personalizados afectan la huella? Los encabezados que no forman parte del conjunto estándar (como X-Custom-Header) no afectan la huella del navegador; son simplemente campos adicionales en la solicitud.

¿Puedo eliminar un encabezado estándar? BotBrowser no permite eliminar encabezados estándar mediante encabezados personalizados. Los encabezados gestionados por el perfil se incluyen siempre para mantener la consistencia de la huella.

¿--bot-custom-headers funciona con --proxy-server? Sí. Los encabezados se añaden independientemente de si se utiliza un proxy; el proxy verá el conjunto completo de encabezados.

¿Hay un número máximo de encabezados personalizados? No hay un límite explícito. Sin embargo, un conjunto demasiado grande de encabezados puede aumentar el tamaño de la solicitud y activar límites del servidor.

¿Puedo usar --bot-custom-headers para encabezados Cookie? Para gestión de cookies, usa la bandera dedicada --bot-cookies. Proporciona manejo correcto de ámbito de dominio y expiración.

Resumen

El control de encabezados HTTP es esencial para mantener una identidad de navegador consistente. BotBrowser ofrece gestión de encabezados a nivel de motor mediante perfiles (para encabezados estándar), la bandera --bot-custom-headers (para encabezados personalizados estáticos) y el comando CDP BotBrowser.setCustomHeaders (para encabezados dinámicos en tiempo de ejecución). Estas herramientas garantizan que cada solicitud lleve información de encabezados completa y consistente.

Temas relacionados: Proxy Configuration y User Agent Control and Client Hints。 Para gestión de identidad multicuenta, ver Multi-Account Browser Isolation.

title: "Headers HTTP personalizados: Controla los headers de solicitud con BotBrowser" description: "Aprende a establecer headers HTTP personalizados usando el flag --bot-custom-headers de BotBrowser para una identidad de navegacion consistente." date: "2025-09-23" locale: es category: network tags: ["http-headers", "custom-headers", "network", "privacy", "request"] published: true

Por que importa el control de headers

Los headers HTTP como User-Agent, Accept-Language y Sec-CH-UA son parte de la identidad de tu navegador. BotBrowser gestiona automaticamente todos los headers estandar a traves de perfiles y te permite agregar headers personalizados a nivel del motor.

Consistencia de headers basada en perfiles

Al cargar un perfil de huella digital con --bot-profile, BotBrowser alinea automaticamente todos los headers estandar con la identidad del perfil.

chrome --bot-profile="/path/to/profile.enc" \
       --bot-config-locale="de-DE" \
       --bot-config-languages="de-DE,de,en-US,en" \
       --user-data-dir="$(mktemp -d)"

Agregar headers personalizados

El flag --bot-custom-headers te permite establecer headers HTTP adicionales a nivel del motor:

chrome --bot-profile="/path/to/profile.enc" \
       --bot-custom-headers='{"X-Custom-Header":"value","Another-Header":"value2"}' \
       --user-data-dir="$(mktemp -d)"

Los casos de uso incluyen tokens de autenticacion, identificadores especificos de aplicacion y headers de prevencion de rastreo.

Modificacion a nivel de motor

Como BotBrowser modifica los headers a nivel del motor Chromium, los cambios se aplican a todas las solicitudes:

  • Cargas de pagina iniciales
  • Solicitudes de subrecursos (imagenes, scripts, hojas de estilo)
  • Solicitudes XHR y Fetch API
  • Solicitudes de actualizacion WebSocket

Ejemplo con Puppeteer

const puppeteer = require('puppeteer-core');

const browser = await puppeteer.launch({
  executablePath: '/path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/path/to/profile.enc',
    '--bot-custom-headers={"X-Auth":"token123"}',
  ],
  headless: true,
  defaultViewport: null,
});

const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

Verificacion

  1. Abre DevTools y revisa la pestana Network para los headers de solicitud
  2. Verifica que los headers personalizados aparezcan en todos los tipos de solicitud
  3. Confirma que los headers estandar coincidan con el perfil cargado

Primeros pasos

  1. Descarga BotBrowser desde GitHub
  2. Carga un perfil de huella digital con --bot-profile
  3. Agrega headers personalizados con --bot-custom-headers
  4. Verifica la consistencia de headers en todos los tipos de solicitud
#http-headers#custom-headers#network#privacy#request