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"
  }
}

Compara esta firma con monitor.monitor_id en los payloads entrantes para verificar la autenticidad.

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": {
    "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": {
    "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.

Las señales de expansión se agrupan por empresa y mercado, no por señal. Una empresa que entra en dos mercados produce dos entradas, cada una con la línea de tiempo de señales propia de ese mercado.

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": {
    "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.

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

Payload de señal de expansión

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

​Payload de señal de expansión

​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

Payload de señal de expansión

Destino por correo electrónico

Solución de problemas