Setting up Webhooks

Webhooks are the recommended way to receive monitor results. When a monitor triggers, Pubrio sends a POST request with a JSON payload to your configured URL — in real-time.

Prerequisites

A Pubrio API key with monitor access
A publicly accessible HTTPS endpoint (or a test URL from usewebhook.com)

Quick testing: Use usewebhook.com to generate a free temporary webhook URL. You can inspect every incoming payload without deploying anything.

Step 1: Create a Monitor with Webhook Destination

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

Response:

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

The headers object adds custom HTTP headers to every delivery (useful for authentication). The body object adds custom fields to the root of the webhook payload.

Save the signature from the response — you will need it to verify incoming payloads. It is only returned at creation time, via the Signature Reveal endpoint, or from Monitor Lookup with is_signature_reveal: true.

Step 2: Validate Your Webhook Connection

Use the Validate Webhook endpoint to test that your endpoint is reachable. This sends a sample payload with placeholder data — no credits are consumed, no real signals are fetched.

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

A successful response returns the sample request payload that was sent and the response your endpoint returned — so you can confirm the connection works before going live.

Step 3: Test with Real Data

Once the connection is validated, trigger a real run using the Process Try endpoint. This fetches actual signals and delivers them to your webhook — use tried_at with a recent past date to ensure data is available:

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

Unlike validate, the try endpoint runs a real scan and consumes credits. Use it to verify real payloads arrive correctly and to get a quick estimate of results before the scheduled scan kicks in.

Step 4: Verify Signatures

Each monitor has a secret signature (a UUID). Reveal it once and keep it on your side:

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

Every delivery carries two headers:

Header	Value
`x-pubrio-signature`	The monitor’s secret, as revealed above.
`x-pubrio-signature-256`	Hex HMAC-SHA256 of the raw request body, keyed with that secret.

Verify the HMAC over the exact bytes you received, before parsing the JSON:

Node.js

const crypto = require("crypto");
const expected = crypto.createHmac("sha256", MONITOR_SECRET).update(rawBody).digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers["x-pubrio-signature-256"]));

The plain header is kept for receivers that already compare it; prefer the HMAC.

Webhook Payload Structure

Payloads differ based on the monitor’s detection_mode:

Signal First
Company First

In signal_first mode, the payload contains a top-level signals array:

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

Each signal entry contains the signal details and the associated enriched companies and people.

In company_first mode, the payload contains a top-level companies array with enriched company data and nested signals:

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

Each company in the array includes the full enriched profile, all matching signals, and enriched people contacts.

Custom body fields from destination_config appear at the root level of the payload (e.g., "pipeline": "my-webhook" when configured in your destination).

Expansion Signals

Alongside jobs, news and advertisements, a monitor can watch expansion signals — the dated evidence that a company is entering or growing in a new market. Add expansions to 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 filters use the Expansion Search vocabulary, not the job/news/ad one — froms and tos for the corridor, plus stages, scopes, momentum, freshness, signal_types, signal_subtypes, signal_strengths, source_types and window_days. Resolve the valid slugs from Expansion Reference.

A webhook delivers expansion signals at the monitor’s record unit. At the default signal unit (signal_first) each entry is one raw signal (HIRE, AD, OFFICE…) whose companies[0] carries the (company, market) card; country_code is the market. Set record_unit: "company" to receive one entry per company with its signals nested. The email digest always groups per company and market.

Cloud Footprint

DNS is the cloud footprint signal — a company standing up cloud or hosting infrastructure in a market. Narrow an expansion monitor to it with signal_types inside the expansion filters:

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

Every delivery carries evidence_url, a Pubrio page backing the signal. Raw infrastructure detail is never included in the payload. For the same hosts as a plain event stream with provider, region and city filters, use the dedicated cloud_footprints signal type below.

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

Each companies[0] card also carries the stage read: stage_slug, expansion_score, confidence_score, direction, freshness, signal_count, first_signal_at, latest_signal_at and last_transition_at. Field-by-field meanings live in the Expansion Field Reference. To pull the same rows on demand rather than on a trigger, use Expansion Signal Search.

Cloud Footprint Signals

Add cloud_footprints to signal_types to receive one record per host a company stands up in a market outside its home country: a new server on a cloud or hosting provider, or one that moved region or country. It is the same infrastructure evidence the expansion DNS signal reads, delivered as a plain event stream instead of a market stage: every host, in arrival order, with the footprint’s own filters and no stage, score or window.

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

Filter	Meaning
`providers` / `exclude_providers`	Cloud or hosting provider, as named by Cloud Footprint Search
`cloud_regions` / `exclude_cloud_regions`	Provider region codes, e.g. `eu-central-1`
`cities` / `exclude_cities`	Data-centre cities
`country_codes`	Country the host sits in

Each signal carries provider, cloud_region, city, novelty, country_code, country_name, event_date, a localised display_label such as AWS · Frankfurt, and evidence_url. Raw host names and IP addresses are never included. Home-market infrastructure is not in this stream.

Delivery Rules

What one record is

A record is what the caps count and what a delivery entry is. By default it follows the detection mode: signal_first delivers signals (one signals[] entry per job, ad, article or expansion signal), company_first delivers companies (one companies[] entry per company with its signals nested). Set record_unit to choose explicitly, for example record_unit: "company" on a signal_first advertisements monitor delivers one entry per advertiser instead of one per ad.

Excluding companies

excluded_companies (plus excluded_domains and excluded_linkedin_urls, resolved the same way as companies) is a never-deliver list: an excluded company is dropped before enrichment and billing in both detection modes, and a company_first watch list skips it while it stays on the list. Both the watch list (companies, domains, linkedin_urls) and the exclusion list share one limit of 100,000 companies per monitor, enough for a CRM export. A list above the limit is rejected, never cut. Update Monitor replaces a list you send and leaves one you omit; send companies_mode or excluded_companies_mode as add or remove to change only the entries you send, which is how a CRM sync keeps a list current without re-sending it. Create, Update and Try answer with metadata.unresolved, naming every domain or LinkedIn URL no company answered to, per list, so nothing is dropped silently.

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

To exclude whole industries instead of named companies, use company_filters with the Company Search exclusion keys: exclude_vertical_categories, exclude_vertical_sub_categories, exclude_verticals and exclude_technologies. They apply to every signal type, advertisements included.

Caps

Parameter	Counts	Behaviour
`max_records_per_trigger`	records in one delivery	The rest is carried over: jobs, news and advertisements keep a per-type cursor, so the next trigger continues where this one stopped. Expansion signals use a date window that restarts at the oldest record the cap left out, so their overflow is carried over too.
`max_daily_trigger`	non-empty, successful deliveries per calendar day (owner’s timezone)	An empty trigger (no matching signal) and a failed delivery do not count.
`max_daily_records`	records per calendar day (owner’s timezone)	A hard limit: a trigger delivers at most the remaining budget, then the monitor waits for the next day without moving its cursor.

A list of any size reads back page by page: Company Search with company_groups: [source_group_id] (or excluded_group_id), both returned by Lookup Monitor, which also returns the full lists.

Freshest first

By default a monitor delivers in arrival order, oldest first, and a cap carries the rest over, so a day’s backlog is worked through before newer signals. Set is_newest_first: true to flip that: each run delivers the newest matching records, and whatever a cap leaves out is skipped for good, never queued. This holds for every signal type and for a monitor resuming after a pause or an exhausted daily budget.

Deduplication and re-delivery

A signal is never delivered twice. Every successful delivery logs the keys of the signals it carried, and every run drops any candidate already in that log, for all signal types. Jobs, news and advertisements also keep a per-type cursor, so a delivered signal is not even fetched again.
company_dedupe_days: N guarantees a company appears in at most one delivery per N days across all the monitor’s signal types; its later signals inside the window are skipped.
Every payload carries metadata.monitor_log_id (the Statistic Logs row of that attempt) and metadata.parent_monitor_log_id (null on a first attempt; on a retry, automatic or via Process Retry, the first attempt’s id). The same signals can only reach you again through such a retry, so deduplicate on parent_monitor_log_id || monitor_log_id. A retry replays the first attempt’s payload as it was; send is_use_original_payload: false to re-apply today’s rules first (exclusions and both ledgers), in which case a retry with nothing left is skipped with code 40085.

Email Destination

For teams that prefer email delivery, set destination_type to "email":

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

Pubrio supports white-label email delivery for agencies and teams. Get in touch to learn about customizing the sender domain and branding.

Troubleshooting

Webhook not receiving payloads

Verify your endpoint is publicly accessible (not behind a firewall or VPN)
Ensure it returns a 200 status code — other codes are treated as failures
Use the Validate Webhook endpoint to test connectivity
Check Statistic Logs for error messages and response codes

Monitor paused after failures

If your webhook returns non-200 codes consistently, the monitor pauses after reaching max_failure_trigger consecutive failures. Fix the issue and reactivate via Update Monitor.

Duplicate payloads

If a delivery fails and retries are configured, you may receive the same payload multiple times. Use triggered_at or the log ID to deduplicate on your end.

Payload too large

Reduce max_records_per_trigger to limit records per delivery. You can also narrow your filters to reduce matching signal volume.

Monitor

Search

Filters

People

Expansion

Prerequisites

Step 1: Create a Monitor with Webhook Destination

Step 2: Validate Your Webhook Connection

Step 3: Test with Real Data

Step 4: Verify Signatures

Webhook Payload Structure

Expansion Signals

Cloud Footprint

Expansion Signal Payload

Cloud Footprint Signals

Delivery Rules

What one record is

Excluding companies

Caps

Freshest first

Deduplication and re-delivery

Email Destination

Troubleshooting

​Prerequisites

​Step 1: Create a Monitor with Webhook Destination

​Step 2: Validate Your Webhook Connection

​Step 3: Test with Real Data

​Step 4: Verify Signatures

​Webhook Payload Structure

​Expansion Signals

​Cloud Footprint

​Expansion Signal Payload

​Cloud Footprint Signals

​Delivery Rules

​What one record is

​Excluding companies

​Caps

​Freshest first

​Deduplication and re-delivery

​Email Destination

​Troubleshooting

Prerequisites

Step 1: Create a Monitor with Webhook Destination

Step 2: Validate Your Webhook Connection

Step 3: Test with Real Data

Step 4: Verify Signatures

Webhook Payload Structure

Expansion Signals

Cloud Footprint

Expansion Signal Payload

Cloud Footprint Signals

Delivery Rules

What one record is

Excluding companies

Caps

Freshest first

Deduplication and re-delivery

Email Destination

Troubleshooting