Настройка вебхуков

Вебхуки — рекомендуемый способ получения результатов монитора. Когда монитор срабатывает, Pubrio отправляет POST-запрос с JSON payload на ваш настроенный URL — в реальном времени.

Предварительные требования

Ключ API Pubrio с доступом к мониторам
Публично доступный HTTPS-эндпоинт (или тестовый URL с usewebhook.com)

Быстрое тестирование: используйте usewebhook.com, чтобы сгенерировать бесплатный временный URL вебхука. Вы можете просматривать каждый входящий payload без развёртывания чего-либо.

Шаг 1: создайте монитор с назначением-вебхуком

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());

Ответ:

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

Объект headers добавляет пользовательские HTTP-заголовки к каждой доставке (полезно для аутентификации). Объект body добавляет пользовательские поля в корень payload’а вебхука.

Сохраните signature из ответа — она понадобится вам для верификации входящих payload’ов. Она возвращается только при создании, через эндпоинт Signature Reveal, либо из Monitor Lookup с is_signature_reveal: true.

Шаг 2: проверьте подключение вебхука

Используйте эндпоинт Validate Webhook, чтобы протестировать доступность вашего эндпоинта. Он отправляет тестовый payload с данными-заглушками — кредиты не расходуются, реальные сигналы не запрашиваются.

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

Успешный ответ возвращает отправленный тестовый payload запроса и ответ, который вернул ваш эндпоинт — так вы можете подтвердить, что соединение работает, прежде чем выходить в продакшн.

Шаг 3: протестируйте на реальных данных

После проверки соединения запустите реальный прогон с помощью эндпоинта Process Try. Он получает реальные сигналы и доставляет их на ваш вебхук — используйте tried_at с недавней прошедшей датой, чтобы обеспечить доступность данных:

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

В отличие от validate, эндпоинт try выполняет реальное сканирование и расходует кредиты. Используйте его, чтобы убедиться, что реальные payload’ы приходят корректно, и получить быструю оценку результатов до запуска планового сканирования.

Шаг 4: верифицируйте подписи

У каждого монитора есть уникальная подпись для верификации того, что входящие payload’ы действительно от 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"
  }
}

Каждая доставка несёт два заголовка: x-pubrio-signature (секрет, полученный выше) и x-pubrio-signature-256 (hex HMAC-SHA256 сырого тела запроса с этим секретом в качестве ключа). Проверяйте HMAC по полученным байтам до разбора JSON.

Структура payload’а вебхука

Payload’ы отличаются в зависимости от detection_mode монитора:

Signal First
Company First

В режиме signal_first payload содержит массив signals верхнего уровня:

{
  "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": [...],
      ...
    },
    ...
  ]
}

Каждая запись сигнала содержит детали сигнала и связанные обогащённые компании и людей.

В режиме company_first payload содержит массив companies верхнего уровня с обогащёнными данными компаний и вложенными сигналами:

{
  "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": [...],
      ...
    },
    ...
  ]
}

Каждая компания в массиве включает полный обогащённый профиль, все совпавшие сигналы и обогащённые контакты людей.

Пользовательские поля body из destination_config появляются в корне payload’а (например, "pipeline": "my-webhook", если это настроено в вашем назначении).

Сигналы экспансии

Наряду с jobs, news и advertisements, монитор может отслеживать сигналы экспансии — датированные доказательства того, что компания выходит на новый рынок или растёт на нём. Добавьте expansions в 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"
  }
}

Фильтры экспансии используют словарь Expansion Search, а не словарь вакансий/новостей/рекламы — froms и tos для коридора, плюс stages, scopes, momentum, freshness, signal_types, signal_subtypes, signal_strengths, source_types и window_days. Разрешите допустимые slug из Expansion Reference.

Вебхук доставляет сигналы экспансии в единице записи монитора. При единице signal по умолчанию (signal_first) каждая запись — один сырой сигнал (HIRE, AD, OFFICE…), чей companies[0] несёт карточку (компания, рынок); country_code — это рынок. Задайте record_unit: "company", чтобы получать одну запись на компанию с вложенными сигналами. Email-дайджест всегда группирует по компании и рынку.

Облачный след

DNS — сигнал облачного следа: компания разворачивает облачную или хостинговую инфраструктуру на рынке. Сузьте монитор расширения через signal_types внутри фильтров:

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

Каждая доставка содержит evidence_url — страницу Pubrio, подтверждающую сигнал. Сырые данные об инфраструктуре в полезную нагрузку не попадают. Чтобы получать те же хосты как чистый поток событий с фильтрами по провайдеру, региону и городу, используйте отдельный тип сигнала cloud_footprints ниже.

Payload сигнала экспансии

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

Значения по каждому полю приведены в Expansion Field Reference. Чтобы получать те же строки по запросу, а не по триггеру, используйте Expansion Signal Search.

Сигналы облачного следа

Добавьте cloud_footprints в signal_types, чтобы получать по записи на каждый хост, который компания разворачивает на рынке за пределами своей страны: новый сервер у облачного или хостинг-провайдера либо сервер, сменивший регион или страну. Это та же инфраструктурная улика, что читает сигнал экспансии DNS, но доставляется как чистый поток событий, а не как этап рынка: каждый хост в порядке поступления, с собственными фильтрами следа, без этапов, оценок и окон.

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

Фильтр	Значение
`providers` / `exclude_providers`	Облачный или хостинг-провайдер, как его называет Cloud Footprint Search
`cloud_regions` / `exclude_cloud_regions`	Коды регионов провайдера, например `eu-central-1`
`cities` / `exclude_cities`	Города дата-центров
`country_codes`	Страна, где находится хост

Каждый signal содержит provider, cloud_region, city, novelty, country_code, country_name, event_date, локализованный display_label вроде AWS · Frankfurt и evidence_url. Сырые имена хостов и IP-адреса никогда не включаются. Инфраструктура домашнего рынка в этот поток не входит.

Правила доставки

Что такое одна запись

Запись — это то, что считают лимиты, и одна позиция доставки. По умолчанию она следует режиму обнаружения: signal_first доставляет сигналы (одна позиция signals[] на вакансию, объявление, статью или сигнал экспансии), company_first доставляет компании (одна позиция companies[] на компанию с вложенными сигналами). Задайте record_unit, чтобы выбрать явно: например, record_unit: "company" на мониторе объявлений signal_first даёт одну позицию на рекламодателя вместо одной на объявление.

Исключение компаний

excluded_companies (а также excluded_domains и excluded_linkedin_urls, разрешаемые так же, как companies) — список «никогда не доставлять»: исключённая компания отбрасывается до обогащения и списания в обоих режимах, а список наблюдения company_first пропускает её, пока она в списке. До 100 000 компаний на монитор — хватает на экспорт существующих клиентов из CRM. В Update Monitor передайте companies_mode или excluded_companies_mode как add / remove, чтобы изменить только отправленные записи, не пересылая весь список.

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

Лимиты

Параметр	Что считает	Поведение
`max_records_per_trigger`	записи в одной доставке	Остальное переносится: вакансии, новости и объявления хранят курсор по типу, и следующий запуск продолжает с места остановки. Сигналы экспансии читаются по окну дат, которое начинается заново с самой старой записи, не вошедшей в лимит, поэтому их излишек тоже переносится.
`max_daily_trigger`	непустые успешные доставки за календарный день (часовой пояс владельца)	Пустой запуск (нет совпадений) и неудачная доставка не считаются.
`max_daily_records`	записи за календарный день (часовой пояс владельца)	Жёсткий лимит: запуск доставляет не больше остатка бюджета, затем монитор ждёт следующего дня, не сдвигая курсор.

Список любого размера читается постранично: Company Search с company_groups: [source_group_id] (или excluded_group_id); оба id возвращает Lookup Monitor, который возвращает и полные списки.

Сначала самое новое

По умолчанию монитор доставляет записи в порядке поступления, сначала самые старые, а лимит переносит остаток, поэтому накопившееся за день обрабатывается раньше новых сигналов. is_newest_first: true меняет это: каждый запуск доставляет самые свежие подходящие записи, а то, что не вошло в лимит, пропускается навсегда и не ставится в очередь. Это действует для всех типов сигналов и для монитора, который возобновляет работу после паузы или исчерпанного дневного бюджета.

Дедупликация и повторная доставка

Сигнал никогда не доставляется дважды. Каждая успешная доставка записывает ключи своих сигналов, и каждый запуск отбрасывает кандидатов, уже имеющихся в журнале, для всех типов сигналов. Вакансии, новости и объявления также хранят курсор по типу, так что доставленный сигнал даже не выбирается снова.
company_dedupe_days: N гарантирует, что компания появится не более чем в одной доставке за N дней по всем типам сигналов монитора; её последующие сигналы внутри окна пропускаются.
Каждый payload содержит metadata.monitor_log_id (строка Журнала статистики для этой попытки) и metadata.parent_monitor_log_id (null при первой попытке; при повторе, автоматическом или через Повтор обработки, id первой попытки). Те же сигналы могут прийти снова только через такой повтор, поэтому дедуплицируйте по parent_monitor_log_id || monitor_log_id. Повтор по умолчанию отправляет payload первой попытки как есть; передайте is_use_original_payload: false, чтобы сначала заново применить текущие правила (исключения и оба журнала), и тогда повтор, в котором ничего не осталось, пропускается с кодом 40085.

Назначение по email

Для команд, предпочитающих доставку по email, установите destination_type в "email":

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

Pubrio поддерживает доставку email под white-label для агентств и команд. Свяжитесь с нами, чтобы узнать о настройке домена отправителя и брендинга.

Устранение неполадок

Вебхук не получает payload'ы

Убедитесь, что ваш эндпоинт публично доступен (не за файрволом или VPN)
Убедитесь, что он возвращает код статуса 200 — остальные коды считаются сбоями
Используйте эндпоинт Validate Webhook, чтобы проверить связность
Проверьте Statistic Logs на предмет сообщений об ошибках и кодов ответа

Монитор приостановлен после сбоев

Если ваш вебхук постоянно возвращает коды, отличные от 200, монитор приостанавливается после достижения max_failure_trigger последовательных сбоев. Устраните проблему и реактивируйте через Update Monitor.

Дублирующиеся payload'ы

Если доставка завершается ошибкой и настроены повторные попытки, вы можете получить один и тот же payload несколько раз. Используйте triggered_at или ID журнала, чтобы дедуплицировать на своей стороне.

Payload слишком большой

Уменьшите max_records_per_trigger, чтобы ограничить количество записей на доставку. Вы также можете сузить фильтры, чтобы уменьшить объём совпадающих сигналов.

Мониторинг

Поиск

Фильтры

Люди

Экспансия

Настройка вебхуков

Предварительные требования

Шаг 1: создайте монитор с назначением-вебхуком

Шаг 2: проверьте подключение вебхука

Шаг 3: протестируйте на реальных данных

Шаг 4: верифицируйте подписи

Структура payload’а вебхука

Сигналы экспансии

Облачный след

Payload сигнала экспансии

Сигналы облачного следа

Правила доставки

Что такое одна запись

Исключение компаний

Лимиты

Сначала самое новое

Дедупликация и повторная доставка

Назначение по email

Устранение неполадок

​Предварительные требования

​Шаг 1: создайте монитор с назначением-вебхуком

​Шаг 2: проверьте подключение вебхука

​Шаг 3: протестируйте на реальных данных

​Шаг 4: верифицируйте подписи

​Структура payload’а вебхука

​Сигналы экспансии

​Облачный след

​Payload сигнала экспансии

​Сигналы облачного следа

​Правила доставки

​Что такое одна запись

​Исключение компаний

​Лимиты

​Сначала самое новое

​Дедупликация и повторная доставка

​Назначение по email

​Устранение неполадок

Предварительные требования

Шаг 1: создайте монитор с назначением-вебхуком

Шаг 2: проверьте подключение вебхука

Шаг 3: протестируйте на реальных данных

Шаг 4: верифицируйте подписи

Структура payload’а вебхука

Сигналы экспансии

Облачный след

Payload сигнала экспансии

Сигналы облачного следа

Правила доставки

Что такое одна запись

Исключение компаний

Лимиты

Сначала самое новое

Дедупликация и повторная доставка

Назначение по email

Устранение неполадок