Configurar Webhooks

Los webhooks son la forma recomendada de recibir los resultados de un monitor. Cuando un monitor se dispara, Pubrio envía una solicitud POST con un payload JSON a tu URL configurada — en tiempo real.

Requisitos previos

Una API key de Pubrio con acceso a monitores
Un endpoint HTTPS accesible públicamente (o una URL de prueba de usewebhook.com)

Prueba rápida: Usa usewebhook.com para generar una URL de webhook temporal y gratuita. Puedes inspeccionar cada payload entrante sin desplegar nada.

Paso 1: Crear un Monitor con destino Webhook

curl -X POST https://api.pubrio.com/monitors/create \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "name": "My First Monitor",
    "detection_mode": "signal_first",
    "signal_types": ["jobs"],
    "signal_filters": [
      {
        "signal_type": "jobs",
        "filters": {
          "locations": ["US"]
        }
      }
    ],
    "destination_type": "webhook",
    "destination_config": {
      "webhook_url": "https://usewebhook.com/YOUR_WEBHOOK_ID",
      "headers": {
        "X-Custom-Auth": "your-secret-token"
      },
      "body": {
        "pipeline": "my-webhook"
      }
    },
    "max_records_per_trigger": 5,
    "profile_id": 1
  }'

import requests

response = requests.post(
    "https://api.pubrio.com/monitors/create",
    headers={
        "Content-Type": "application/json",
        "pubrio-api-key": "YOUR_API_KEY"
    },
    json={
        "name": "My First Monitor",
        "detection_mode": "signal_first",
        "signal_types": ["jobs"],
        "signal_filters": [
            {
                "signal_type": "jobs",
                "filters": {
                    "locations": ["US"]
                }
            }
        ],
        "destination_type": "webhook",
        "destination_config": {
            "webhook_url": "https://usewebhook.com/YOUR_WEBHOOK_ID",
            "headers": {
                "X-Custom-Auth": "your-secret-token"
            },
            "body": {
                "pipeline": "my-webhook"
            }
        },
        "max_records_per_trigger": 5,
        "profile_id": 1
    }
)

print(response.json())

const response = await fetch("https://api.pubrio.com/monitors/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "pubrio-api-key": "YOUR_API_KEY"
  },
  body: JSON.stringify({
    name: "My First Monitor",
    detection_mode: "signal_first",
    signal_types: ["jobs"],
    signal_filters: [
      {
        signal_type: "jobs",
        filters: {
          locations: ["US"]
        }
      }
    ],
    destination_type: "webhook",
    destination_config: {
      webhook_url: "https://usewebhook.com/YOUR_WEBHOOK_ID",
      headers: {
        "X-Custom-Auth": "your-secret-token"
      },
      body: {
        pipeline: "my-webhook"
      }
    },
    max_records_per_trigger: 5,
    profile_id: 1
  })
});

console.log(await response.json());

Respuesta:

{
  "data": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My First Monitor",
    "detection_mode": "signal_first",
    "destination_type": "webhook",
    "is_active": true,
    "is_paused": false,
    "masked_signature": "7••••••••••••••••8df",
    "created_at": "2026-04-06T10:00:00.000Z",
    "signature": "71a2b3c4-d5e6-f789-0abc-def123456789"
  }
}

El objeto headers añade encabezados HTTP personalizados a cada entrega (útil para autenticación). El objeto body añade campos personalizados a la raíz del payload del webhook.

Guarda el signature de la respuesta — lo necesitarás para verificar los payloads entrantes. Solo se devuelve en el momento de la creación, a través del endpoint Signature Reveal, o desde Monitor Lookup con is_signature_reveal: true.

Paso 2: Validar tu conexión de Webhook

Usa el endpoint Validate Webhook para probar que tu endpoint es accesible. Esto envía un payload de muestra con datos de marcador de posición — no se consumen créditos, no se obtienen señales reales.

curl -X POST https://api.pubrio.com/monitors/webhook/validate \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "detection_mode": "signal_first",
    "signal_types": ["jobs"],
    "signal_filters": [
      {
        "signal_type": "jobs",
        "filters": { "locations": ["US"] }
      }
    ],
    "destination_type": "webhook",
    "destination_config": {
      "webhook_url": "https://usewebhook.com/YOUR_WEBHOOK_ID",
      "headers": { "X-Custom-Auth": "your-secret-token" },
      "body": { "pipeline": "my-webhook" }
    },
    "profile_id": 1
  }'

Una respuesta exitosa devuelve el payload de solicitud de muestra que se envió y la respuesta que devolvió tu endpoint — así puedes confirmar que la conexión funciona antes de pasar a producción.

Paso 3: Probar con datos reales

Una vez validada la conexión, dispara una ejecución real usando el endpoint Process Try. Esto obtiene señales reales y las entrega a tu webhook — usa tried_at con una fecha pasada reciente para asegurar que haya datos disponibles:

curl -X POST https://api.pubrio.com/monitors/process/try \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tried_at": "2026-01-01T00:00:00.000Z",
    "profile_id": 1
  }'

A diferencia de validate, el endpoint try ejecuta un escaneo real y consume créditos. Úsalo para verificar que los payloads reales llegan correctamente y para obtener una estimación rápida de resultados antes de que se ejecute el escaneo programado.

Paso 4: Verificar firmas

Cada monitor tiene una firma única para verificar que los payloads entrantes provienen genuinamente de Pubrio.

curl -X POST https://api.pubrio.com/monitors/signature/reveal \
  -H "Content-Type: application/json" \
  -H "pubrio-api-key: YOUR_API_KEY" \
  -d '{
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "profile_id": 1
  }'

{
  "data": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "signature": "71a2b3c4-d5e6-f789-0abc-def123456789"
  }
}

Cada entrega lleva dos cabeceras: x-pubrio-signature (el secreto revelado arriba) y x-pubrio-signature-256 (HMAC-SHA256 en hexadecimal del cuerpo bruto de la petición, con ese secreto como clave). Verifica el HMAC sobre los bytes recibidos antes de parsear el JSON.

Estructura del payload del Webhook

Los payloads difieren según el detection_mode del monitor:

Signal First
Company First

En modo signal_first, el payload contiene un arreglo signals de nivel superior:

{
  "monitor": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Signal Monitor",
    "detection_mode": "signal_first",
    "signal_types": ["jobs", "news"],
    "signal_filters": [...],
    "company_filters": {...},
    "is_company_enrichment": true,
    "is_people_enrichment": true,
    "people_enrichment_configs": [...]
  },
  "metadata": {
    "monitor_log_id": "3f2b9c1e-7d4a-4c58-9e1f-0a6b2c8d4e55",
    "parent_monitor_log_id": null,
    "total_signals": 3,
    "total_companies": 2,
    "total_people": 5
  },
  "triggered_at": "2026-04-05T20:29:43.832Z",
  "signals": [
    {
      "signal_type": "jobs",
      "signal": {
        "signal_type": "jobs",
        "job_search_id": "...",
        "companies": [
          {
            "domain_search_id": "...",
            "company_name": "...",
            "domain": "...",
            ...
          }
        ],
        ...
      },
      "companies": [
        {
          "domain_search_id": "...",
          "company_name": "...",
          "domain": "...",
          "logo_url": "...",
          "country_code": "...",
          "company_size": 5000,
          "industry": "...",
          "people": [...],
          "emails": [...],
          "phones": [...],
          ...
        }
      ]
    },
    {
      "signal_type": "news",
      "signal": {
        "signal_type": "news",
        "news_search_id": "...",
        "news_id": "...",
        "title": "...",
        "summary": "...",
        "published_at": "...",
        "source": "...",
        "category": "...",
        "companies": [...],
        ...
      },
      "companies": [...],
      ...
    },
    ...
  ]
}

Cada entrada de señal contiene los detalles de la señal y las empresas y personas asociadas ya enriquecidas.

En modo company_first, el payload contiene un arreglo companies de nivel superior con datos de empresa enriquecidos y señales anidadas:

{
  "monitor": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Company Monitor",
    "detection_mode": "company_first",
    "signal_types": ["jobs", "news", "advertisements"],
    "signal_filters": [...],
    "company_filters": {...},
    "is_company_enrichment": true,
    "is_people_enrichment": true,
    "people_enrichment_configs": [...]
  },
  "metadata": {
    "monitor_log_id": "3f2b9c1e-7d4a-4c58-9e1f-0a6b2c8d4e55",
    "parent_monitor_log_id": null,
    "total_signals": 4,
    "total_companies": 2,
    "total_people": 8
  },
  "triggered_at": "2026-04-03T17:45:27.228Z",
  "companies": [
    {
      "company_name": "Acme Corp",
      "domain": "acmecorp.com",
      "domain_search_id": "...",
      "country_code": "US",
      "logo_url": "...",
      "linkedin_name": "acmecorp",
      "company_size": 5200,
      "industry": "Enterprise Software",
      "estimated_revenue": 50000000,
      "founded_year": 2010,
      "company_address": "San Francisco, CA",
      "specialties": ["SaaS", "Cloud Computing", ...],
      "linkedin_url": "https://linkedin.com/company/...",
      "locations": ["US"],
      "signals": [
        {
          "signal_type": "news",
          "signal": {
            "news_id": "...",
            "title": "Acme Corp Launches New AI Product",
            "summary": "...",
            "published_at": "2026-04-03T16:35:00.000Z",
            "source": "techcrunch.com",
            "category": "launches",
            "news_category_name": "Product Launch",
            ...
          }
        },
        {
          "signal_type": "jobs",
          "signal": {
            "job_search_id": "...",
            ...
          }
        },
        ...
      ],
      "people": [
        {
          "name": "Jane Smith",
          "title": "VP of Engineering",
          "email": "[email protected]",
          ...
        },
        ...
      ],
      "emails": ["[email protected]", ...],
      "phones": ["+14155551234", ...],
      "contacts": [...],
      ...
    },
    ...
  ]
}

Cada empresa del arreglo incluye el perfil completo enriquecido, todas las señales coincidentes y los contactos de personas enriquecidos.

Los campos personalizados de body en destination_config aparecen en el nivel raíz del payload (por ejemplo, "pipeline": "my-webhook" cuando se configura en tu destino).

Señales de expansión

Junto con jobs, news y advertisements, un monitor puede vigilar señales de expansión — la evidencia fechada de que una empresa está entrando o creciendo en un nuevo mercado. Añade expansions a signal_types:

{
  "name": "US market entries",
  "detection_mode": "signal_first",
  "signal_types": ["expansions"],
  "signal_filters": [
    {
      "signal_type": "expansions",
      "filters": {
        "tos": ["US"],
        "stages": ["expanding", "scaling"],
        "signal_strengths": ["high", "very_high"],
        "window_days": 30
      }
    }
  ],
  "destination_type": "webhook",
  "destination_config": {
    "webhook_url": "https://usewebhook.com/YOUR_WEBHOOK_ID"
  }
}

Los filtros de expansión usan el vocabulario de Expansion Search, no el de trabajos/noticias/anuncios — froms y tos para el corredor, más stages, scopes, momentum, freshness, signal_types, signal_subtypes, signal_strengths, source_types y window_days. Resuelve los slugs válidos en Expansion Reference.

Un webhook entrega las señales de expansión en la unidad de registro del monitor. En la unidad signal por defecto (signal_first), cada entrada es una señal bruta (HIRE, AD, OFFICE…) cuyo companies[0] lleva la ficha (empresa, mercado); country_code es el mercado. Define record_unit: "company" para recibir una entrada por empresa con sus señales anidadas. El resumen por correo siempre agrupa por empresa y mercado.

Huella cloud

DNS es la señal de huella cloud: una empresa desplegando infraestructura cloud o de hosting en un mercado. Acota un monitor de expansión con signal_types dentro de los filtros:

{
  "signal_type": "expansions",
  "filters": { "tos": ["DE"], "signal_types": ["DNS"], "window_days": 30 }
}

Cada envío incluye evidence_url, una página de Pubrio que respalda la señal. El detalle bruto de la infraestructura nunca se incluye. Para recibir los mismos hosts como un flujo de eventos plano con filtros de proveedor, región y ciudad, usa el tipo de señal dedicado cloud_footprints más abajo.

Payload de señal de expansión

{
  "monitor": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "US market entries",
    "detection_mode": "signal_first",
    "signal_types": ["expansions"],
    "signal_filters": [...]
  },
  "metadata": {
    "monitor_log_id": "3f2b9c1e-7d4a-4c58-9e1f-0a6b2c8d4e55",
    "parent_monitor_log_id": null,
    "total_signals": 2,
    "total_companies": 1,
    "total_people": 0
  },
  "triggered_at": "2026-08-14T09:12:04.551Z",
  "signals": [
    {
      "signal_type": "expansions",
      "signal": {
        "signal_type": "expansions",
        "expansion_signal_id": 90211,
        "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
        "country_code": "US",
        "signal_type_slug": "HIRE",
        "signal_type_name": "Hiring",
        "signal_subtype_slug": "country_manager",
        "signal_strength_slug": "high",
        "polarity": "expansion",
        "event_date": "2026-08-13T14:00:00.000Z",
        "event_date_precision": "day",
        "source_type": "linkedin",
        "display_label": "Hired Country Manager",
        "evidence_url": "https://linkedin.com/company/example-corp",
        "metadata": {...},
        "companies": [
          {
            "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
            "company_name": "Example Corp",
            "domain": "example.com",
            "stage_name": "Expanding",
            "stage_description": "...",
            "home_country": "GB",
            "home_country_name": "United Kingdom",
            "target_country": "US",
            "target_country_name": "United States",
            "estimated_employees": 420,
            "linkedin_url": "https://linkedin.com/company/example-corp"
          }
        ]
      },
      "companies": [...]
    }
  ]
}

El significado de cada campo está en la Referencia de campos de expansión. Para obtener las mismas filas bajo demanda en lugar de en un disparador, usa Expansion Signal Search.

Señales de huella en la nube

Añade cloud_footprints a signal_types para recibir un registro por cada host que una empresa levanta en un mercado fuera de su país: un servidor nuevo en un proveedor de nube u hosting, o uno que cambió de región o de país. Es la misma evidencia de infraestructura que lee la señal de expansión DNS, entregada como un flujo de eventos plano en lugar de una etapa de mercado: cada host, en orden de llegada, con los filtros propios de la huella y sin etapa, puntuación ni ventana.

{
  "signal_types": ["cloud_footprints"],
  "signal_filters": [
    { "signal_type": "cloud_footprints", "filters": { "providers": ["AWS", "Hetzner"], "country_codes": ["DE", "SG"] } }
  ]
}

Filtro	Significado
`providers` / `exclude_providers`	Proveedor de nube u hosting, con el nombre que usa Cloud Footprint Search
`cloud_regions` / `exclude_cloud_regions`	Códigos de región del proveedor, p. ej. `eu-central-1`
`cities` / `exclude_cities`	Ciudades de los centros de datos
`country_codes`	País donde está el host

Cada signal lleva provider, cloud_region, city, novelty, country_code, country_name, event_date, un display_label localizado como AWS · Frankfurt y evidence_url. Nunca se incluyen nombres de host ni direcciones IP en bruto. La infraestructura del mercado local no está en este flujo.

Reglas de entrega

Qué es un registro

Un registro es lo que cuentan los límites y lo que constituye una entrada de entrega. Por defecto sigue al modo de detección: signal_first entrega señales (una entrada signals[] por oferta, anuncio, artículo o señal de expansión), company_first entrega empresas (una entrada companies[] por empresa con sus señales anidadas). Usa record_unit para elegir explícitamente; por ejemplo, record_unit: "company" en un monitor de anuncios signal_first entrega una entrada por anunciante en lugar de una por anuncio.

Excluir empresas

excluded_companies (más excluded_domains y excluded_linkedin_urls, resueltos igual que companies) es una lista de nunca entregar: una empresa excluida se descarta antes del enriquecimiento y la facturación en ambos modos, y la lista de seguimiento de company_first la omite mientras siga en la lista. Hasta 100.000 empresas por monitor, suficiente para una exportación de clientes actuales desde el CRM. En Update Monitor, envía companies_mode o excluded_companies_mode como add / remove para cambiar solo las entradas enviadas, sin reenviar toda la lista.

{
  "excluded_domains": ["existing-client.com", "competitor.io"]
}

Límites

Parámetro	Cuenta	Comportamiento
`max_records_per_trigger`	registros en una entrega	El resto se traslada: ofertas, noticias y anuncios mantienen un cursor por tipo, así que el siguiente disparo continúa donde se detuvo este. Las señales de expansión usan una ventana de fechas que se reinicia en el registro más antiguo que el límite dejó fuera, así que su excedente también se traslada.
`max_daily_trigger`	entregas exitosas no vacías por día natural (zona horaria del propietario)	Un disparo vacío (sin señales coincidentes) y una entrega fallida no cuentan.
`max_daily_records`	registros por día natural (zona horaria del propietario)	Límite estricto: un disparo entrega como máximo el presupuesto restante y luego el monitor espera al día siguiente sin mover su cursor.

Una lista de cualquier tamaño se lee página a página: Company Search con company_groups: [source_group_id] (o excluded_group_id); ambos ids los devuelve Lookup Monitor, que también devuelve las listas completas.

Deduplicación y reentrega

Una señal nunca se entrega dos veces. Cada entrega exitosa registra las claves de las señales que llevó, y cada ejecución descarta cualquier candidata ya presente en ese registro, para todos los tipos de señal. Ofertas, noticias y anuncios mantienen además un cursor por tipo, así que una señal entregada ni siquiera se vuelve a obtener.
company_dedupe_days: N garantiza que una empresa aparezca como máximo en una entrega cada N días en todos los tipos de señal del monitor; sus señales posteriores dentro de la ventana se omiten.
Cada payload lleva metadata.monitor_log_id (la fila de Registros estadísticos de ese intento) y metadata.parent_monitor_log_id (null en un primer intento; en un reintento, automático o mediante Reintento de proceso, el id del primer intento). Las mismas señales solo pueden volver a llegarte mediante ese reintento, así que deduplica por parent_monitor_log_id || monitor_log_id. Un reintento reenvía el payload del primer intento tal cual; envía is_use_original_payload: false para aplicar antes las reglas actuales (exclusiones y ambos registros), y entonces un reintento sin nada que entregar se omite con el código 40085.

Destino por correo electrónico

Para los equipos que prefieren la entrega por correo electrónico, establece destination_type en "email":

{
  "destination_type": "email",
  "destination_config": {
    "email": "[email protected]"
  }
}

Pubrio soporta entrega de correo electrónico de marca blanca para agencias y equipos. Ponte en contacto para conocer cómo personalizar el dominio del remitente y la marca.

Solución de problemas

El webhook no recibe payloads

Verifica que tu endpoint sea accesible públicamente (no esté detrás de un firewall o VPN)
Asegúrate de que devuelva un código de estado 200 — otros códigos se tratan como fallos
Usa el endpoint Validate Webhook para probar la conectividad
Revisa Statistic Logs para ver mensajes de error y códigos de respuesta

Monitor pausado tras fallos

Si tu webhook devuelve códigos distintos de 200 de forma consistente, el monitor se pausa al alcanzar max_failure_trigger fallos consecutivos. Corrige el problema y reactívalo mediante Update Monitor.

Payloads duplicados

Si una entrega falla y hay reintentos configurados, puedes recibir el mismo payload varias veces. Usa triggered_at o el ID del log para deduplicar en tu extremo.

Payload demasiado grande

Reduce max_records_per_trigger para limitar los registros por entrega. También puedes acotar tus filtros para reducir el volumen de señales coincidentes.

Monitor

Búsqueda

Filtros

Personas

Expansión

Requisitos previos

Paso 1: Crear un Monitor con destino Webhook

Paso 2: Validar tu conexión de Webhook

Paso 3: Probar con datos reales

Paso 4: Verificar firmas

Estructura del payload del Webhook

Señales de expansión

Huella cloud

Payload de señal de expansión

Señales de huella en la nube

Reglas de entrega

Qué es un registro

Excluir empresas

Límites

Lo más reciente primero

Deduplicación y reentrega

Destino por correo electrónico

Solución de problemas

​Requisitos previos

​Paso 1: Crear un Monitor con destino Webhook

​Paso 2: Validar tu conexión de Webhook

​Paso 3: Probar con datos reales

​Paso 4: Verificar firmas

​Estructura del payload del Webhook

​Señales de expansión

​Huella cloud

​Payload de señal de expansión

​Señales de huella en la nube

​Reglas de entrega

​Qué es un registro

​Excluir empresas

​Límites

​Lo más reciente primero

​Deduplicación y reentrega

​Destino por correo electrónico

​Solución de problemas

Requisitos previos

Paso 1: Crear un Monitor con destino Webhook

Paso 2: Validar tu conexión de Webhook

Paso 3: Probar con datos reales

Paso 4: Verificar firmas

Estructura del payload del Webhook

Señales de expansión

Huella cloud

Payload de señal de expansión

Señales de huella en la nube

Reglas de entrega

Qué es un registro

Excluir empresas

Límites

Lo más reciente primero

Deduplicación y reentrega

Destino por correo electrónico

Solución de problemas