设置 Webhook

Webhook 是接收 monitor 结果的推荐方式。当 monitor 触发时，Pubrio 会实时向你配置的 URL 发送一个包含 JSON 负载的 POST 请求。

前提条件

拥有 monitor 访问权限的 Pubrio API 密钥
一个可公开访问的 HTTPS 端点（或来自 usewebhook.com 的测试 URL）

快速测试： 使用 usewebhook.com 生成免费的临时 webhook URL。你可以在不部署任何东西的情况下检查每个传入负载。

步骤 1：创建带有 Webhook 投递目标的 Monitor

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 对象会在 webhook 负载的根级别添加自定义字段。

保存响应中的 signature — 你需要它来验证传入的负载。它仅在创建时、通过签名揭示端点、或在监控查询中设置 is_signature_reveal: true 时返回。

步骤 2：验证你的 Webhook 连接

使用验证 Webhook 端点测试你的端点是否可达。这会发送一个包含占位数据的示例负载——不消耗积分，不获取真实信号。

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

成功的响应会返回发送的示例请求负载以及你的端点返回的响应——这样你可以在上线前确认连接正常。

步骤 3：使用真实数据测试

连接验证通过后，使用处理尝试端点触发一次真实运行。这会获取实际信号并投递到你的 webhook——使用 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 端点运行真实扫描并消耗积分。使用它来验证真实负载正确到达，并在计划扫描启动前快速预估结果。

步骤 4：验证签名

每个 monitor 都有唯一的签名，用于验证传入的负载确实来自 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（用该密钥对原始请求体计算的十六进制 HMAC-SHA256）。请在解析 JSON 之前，对收到的原始字节验证 HMAC。

Webhook 负载结构

负载根据 monitor 的 detection_mode 而不同：

信号优先
公司优先

在 signal_first 模式中，负载包含顶层的 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": [...],
      ...
    },
    ...
  ],
  "pipeline": "my-webhook"
}

每个信号条目包含信号详情以及关联的已补充公司和人员。

在 company_first 模式中，负载包含顶层的 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": [...],
      ...
    },
    ...
  ],
  "pipeline": "my-webhook"
}

数组中的每家公司包含完整的补充档案、所有匹配的信号和补充的人员联系方式。

来自 destination_config 的自定义 body 字段会出现在根级别（例如上面示例中的 "pipeline": "my-webhook"）。

扩张信号

除 jobs、news 和 advertisements 之外，监控还可以侦测扩张信号——即表明某公司正在进入或深耕新市场的带日期证据。只需将 expansions 加入 signal_types：

{
  "name": "进入美国市场",
  "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。有效标识请通过 Expansion Reference 获取。

Webhook 按监控的记录单位投递扩张信号。默认的 signal 单位（signal_first）下，每条记录是一条原始信号（HIRE、AD、OFFICE…），其 companies[0] 携带（公司，市场）卡片，country_code 即市场。设置 record_unit: "company" 可按公司接收一条记录，信号嵌套其中。邮件摘要始终按公司与市场分组。

云足迹

DNS 即云足迹信号 —— 公司在某个市场部署云或托管基础设施。在扩张筛选条件中使用 signal_types 将监控缩小到该信号：

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

每次推送都包含 evidence_url，指向佐证该信号的 Pubrio 页面。推送内容不包含原始基础设施明细。若想以纯事件流接收同样的主机并按服务商、区域、城市筛选，请使用下方专用的 cloud_footprints 信号类型。

扩张信号负载

{
  "monitor": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "进入美国市场",
    "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 Signal Search。

云足迹信号

在 signal_types 中加入 cloud_footprints，即可在公司于本国之外的市场部署主机时收到记录：在云或托管服务商上新出现的服务器，或迁移了区域/国家的服务器。它与扩张信号中的 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 显式选择，例如在 signal_first 广告监控上设置 record_unit: "company"，就会按广告主而非按广告投递。

排除公司

excluded_companies（以及与 companies 同样方式解析的 excluded_domains、excluded_linkedin_urls）是永不投递列表：被排除的公司在两种检测模式下都会在数据增强和计费之前被剔除，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 返回，该接口也会返回完整列表。

去重与重复投递

信号绝不会投递两次。 每次成功投递都会记录其携带的信号键，每次运行都会丢弃已在记录中的候选信号，适用于所有信号类型。职位、新闻、广告还按类型保留游标，已投递的信号甚至不会再次获取。
company_dedupe_days: N 保证同一家公司在 N 天内最多出现在一次投递中（跨该监控的所有信号类型），其窗口内的后续信号会被跳过。
每个载荷都带有 metadata.monitor_log_id（该次尝试在统计日志中的行）和 metadata.parent_monitor_log_id（首次尝试为 null；重试时，无论自动还是通过重试处理，为首次尝试的 ID）。同一批信号只会通过这种重试再次到达，请按 parent_monitor_log_id || monitor_log_id 去重。重试默认原样重放首次尝试的载荷；传 is_use_original_payload: false 可先按当前规则（排除列表和两份台账）重新过滤，若无剩余记录则跳过并返回代码 40085。

电子邮件投递目标

对于偏好电子邮件投递的团队，将 destination_type 设置为 "email"：

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

Pubrio 为代理商和团队提供白标邮件投递支持。联系我们了解自定义发件人域名和品牌。

故障排除

Webhook 未接收到负载

确认你的端点是可公开访问的（不在防火墙或 VPN 后面）
确保它返回 200 状态码——其他状态码会被视为失败
使用验证 Webhook 端点测试连通性
检查统计日志中的错误信息和响应码

Monitor 在失败后暂停

如果你的 webhook 持续返回非 200 状态码，monitor 在达到 max_failure_trigger 次连续失败后会暂停。修复问题后通过更新 Monitor 重新激活。

重复负载

如果投递失败且配置了重试，你可能会多次收到相同的负载。使用 triggered_at 或日志 ID 在你端进行去重。

负载过大

减小 max_records_per_trigger 以限制每次投递的记录数。你也可以缩小筛选范围以减少匹配的信号量。

监控

搜索

筛选器

人员

扩张

前提条件

步骤 1：创建带有 Webhook 投递目标的 Monitor

步骤 2：验证你的 Webhook 连接

步骤 3：使用真实数据测试

步骤 4：验证签名

Webhook 负载结构

扩张信号

云足迹

扩张信号负载

云足迹信号

投递规则

一条记录是什么

排除公司

上限

最新优先

去重与重复投递

电子邮件投递目标

故障排除

​前提条件

​步骤 1：创建带有 Webhook 投递目标的 Monitor

​步骤 2：验证你的 Webhook 连接

​步骤 3：使用真实数据测试

​步骤 4：验证签名

​Webhook 负载结构

​扩张信号

​云足迹

​扩张信号负载

​云足迹信号

​投递规则

​一条记录是什么

​排除公司

​上限

​最新优先

​去重与重复投递

​电子邮件投递目标

​故障排除

前提条件

步骤 1：创建带有 Webhook 投递目标的 Monitor

步骤 2：验证你的 Webhook 连接

步骤 3：使用真实数据测试

步骤 4：验证签名

Webhook 负载结构

扩张信号

云足迹

扩张信号负载

云足迹信号

投递规则

一条记录是什么

排除公司

上限

最新优先

去重与重复投递

电子邮件投递目标

故障排除