> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Setting up Webhooks
> Configure webhook destinations, validate endpoints, verify signatures, and handle payloads.
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](https://usewebhook.com))
**Quick testing:** Use [usewebhook.com](https://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
```bash cURL theme={null}
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
}'
```
```python Python theme={null}
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())
```
```javascript Node.js theme={null}
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:**
```json theme={null}
{
"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](/en/api-reference/endpoint/monitors/signature_reveal) endpoint, or from [Monitor Lookup](/en/api-reference/endpoint/monitors/lookup) with `is_signature_reveal: true`.
***
## Step 2: Validate Your Webhook Connection
Use the [Validate Webhook](/en/api-reference/endpoint/monitors/webhook_validate) 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.
```bash cURL theme={null}
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](/en/api-reference/endpoint/monitors/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:
```bash cURL theme={null}
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 unique signature for verifying that incoming payloads are genuinely from Pubrio.
```bash cURL — Reveal Signature theme={null}
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
}'
```
```json theme={null}
{
"data": {
"monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"signature": "71a2b3c4-d5e6-f789-0abc-def123456789"
}
}
```
Compare this signature against the `monitor.monitor_id` in incoming payloads to verify authenticity.
***
## Webhook Payload Structure
Payloads differ based on the monitor's `detection_mode`:
In `signal_first` mode, the payload contains a top-level `signals` array:
```json theme={null}
{
"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": [...],
...
},
...
]
}
```
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:
```json theme={null}
{
"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": "j.smith@acmecorp.com",
...
},
...
],
"emails": ["info@acmecorp.com", ...],
"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`:
```json theme={null}
{
"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](/en/api-reference/endpoint/expansions/market_lookup) 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](/en/api-reference/endpoint/expansions/types).
Expansion signals are grouped **per company and market**, not per signal. A company moving into two markets produces two entries, each carrying that market's own signal timeline.
### 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:
```json theme={null}
{
"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.
### Expansion Signal Payload
```json theme={null}
{
"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": [...]
}
]
}
```
Field-by-field meanings live in the [Expansion Field Reference](/en/knowledge-base/concepts/expansion-field-reference). To pull the same rows on demand rather than on a trigger, use [Expansion Signal Search](/en/api-reference/endpoint/expansions/signal_search).
***
## Email Destination
For teams that prefer email delivery, set `destination_type` to `"email"`:
```json theme={null}
{
"destination_type": "email",
"destination_config": {
"email": "alerts@your-company.com"
}
}
```
Pubrio supports white-label email delivery for agencies and teams. [Get in touch](https://pubrio.com/en/get-in-touch) to learn about customizing the sender domain and branding.
***
## Troubleshooting
* 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](/en/api-reference/endpoint/monitors/webhook_validate) endpoint to test connectivity
* Check [Statistic Logs](/en/api-reference/endpoint/monitors/statistics_logs) for error messages and response codes
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](/en/api-reference/endpoint/monitors/update).
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.
Reduce `max_records_per_trigger` to limit records per delivery. You can also narrow your filters to reduce matching signal volume.