Skip to main content
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
  }'
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 and via the Signature Reveal endpoint.

​
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 unique signature for verifying that incoming payloads are genuinely from 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"
  }
}
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:
{
  "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.
Custom body fields from destination_config appear at the root level of the payload (e.g., "pipeline": "my-webhook" when configured in your destination).

​
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

  • 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
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.
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.