Webhooks einrichten

Webhooks sind die empfohlene Methode zum Empfangen von Monitor-Ergebnissen. Wenn ein Monitor auslöst, sendet Pubrio in Echtzeit eine POST-Anfrage mit einem JSON-Payload an Ihre konfigurierte URL.

Voraussetzungen

Ein Pubrio-API-Schlüssel mit Monitor-Zugriff
Ein öffentlich erreichbarer HTTPS-Endpunkt (oder eine Test-URL von usewebhook.com)

Schnelles Testen: Verwenden Sie usewebhook.com, um eine kostenlose temporäre Webhook-URL zu erzeugen. Sie können jeden eingehenden Payload prüfen, ohne etwas bereitstellen zu müssen.

Schritt 1: Monitor mit Webhook-Ziel erstellen

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

Antwort:

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

Das headers-Objekt fügt jeder Zustellung benutzerdefinierte HTTP-Header hinzu (nützlich für die Authentifizierung). Das body-Objekt fügt der Wurzel des Webhook-Payloads benutzerdefinierte Felder hinzu.

Speichern Sie die signature aus der Antwort — Sie benötigen sie, um eingehende Payloads zu verifizieren. Sie wird nur bei der Erstellung, über den Endpunkt Signature Reveal oder von Monitor Lookup mit is_signature_reveal: true zurückgegeben.

Schritt 2: Ihre Webhook-Verbindung validieren

Verwenden Sie den Endpunkt Validate Webhook, um zu testen, dass Ihr Endpunkt erreichbar ist. Dies sendet einen Beispiel-Payload mit Platzhalterdaten — es werden keine Credits verbraucht, es werden keine echten Signale abgerufen.

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

Eine erfolgreiche Antwort gibt sowohl den gesendeten Beispiel-Anfrage-Payload als auch die von Ihrem Endpunkt zurückgegebene Antwort zurück — so können Sie die Verbindung bestätigen, bevor Sie live gehen.

Schritt 3: Mit echten Daten testen

Sobald die Verbindung validiert ist, lösen Sie mit dem Endpunkt Process Try einen echten Durchlauf aus. Dieser ruft tatsächliche Signale ab und liefert sie an Ihren Webhook aus — verwenden Sie tried_at mit einem kürzlich vergangenen Datum, um sicherzustellen, dass Daten verfügbar sind:

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

Anders als Validate führt der Try-Endpunkt einen echten Scan aus und verbraucht Credits. Verwenden Sie ihn, um zu überprüfen, dass echte Payloads korrekt ankommen, und um eine schnelle Schätzung der Ergebnisse zu erhalten, bevor der geplante Scan startet.

Schritt 4: Signaturen verifizieren

Jeder Monitor hat eine eindeutige Signatur, mit der Sie überprüfen können, dass eingehende Payloads tatsächlich von Pubrio stammen.

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

Vergleichen Sie diese Signatur mit der monitor.monitor_id in eingehenden Payloads, um die Echtheit zu verifizieren.

Struktur des Webhook-Payloads

Payloads unterscheiden sich je nach detection_mode des Monitors:

Signal First
Company First

Im Modus signal_first enthält der Payload ein signals-Array auf oberster Ebene:

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

Jeder Signal-Eintrag enthält die Signaldetails sowie die zugehörigen angereicherten Unternehmen und Personen.

Im Modus company_first enthält der Payload ein companies-Array auf oberster Ebene mit angereicherten Unternehmensdaten und verschachtelten Signalen:

{
  "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": "[email protected]",
          ...
        },
        ...
      ],
      "emails": ["[email protected]", ...],
      "phones": ["+14155551234", ...],
      "contacts": [...],
      ...
    },
    ...
  ]
}

Jedes Unternehmen im Array enthält das vollständige angereicherte Profil, alle übereinstimmenden Signale und angereicherte Personenkontakte.

Benutzerdefinierte body-Felder aus destination_config erscheinen auf der Wurzelebene des Payloads (z. B. "pipeline": "my-webhook", wenn in Ihrem Ziel konfiguriert).

Expansion-Signale

Neben jobs, news und advertisements kann ein Monitor auch Expansion-Signale beobachten — die datierten Belege dafür, dass ein Unternehmen in einen neuen Markt eintritt oder dort wächst. Fügen Sie expansions zu signal_types hinzu:

{
  "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-Filter verwenden das Vokabular von Expansion Search, nicht das von Jobs/News/Anzeigen — froms und tos für den Korridor, plus stages, scopes, momentum, freshness, signal_types, signal_subtypes, signal_strengths, source_types und window_days. Die gültigen Slugs finden Sie unter Expansion Reference.

Expansion-Signale werden pro Unternehmen und Markt gruppiert, nicht pro Signal. Tritt ein Unternehmen in zwei Märkte ein, entstehen zwei Einträge, jeder mit der eigenen Signal-Zeitleiste dieses Markts.

Payload für Expansion-Signale

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

Die Bedeutung der einzelnen Felder finden Sie in der Expansion Field Reference. Um dieselben Zeilen bei Bedarf statt bei einem Trigger abzurufen, verwenden Sie Expansion Signal Search.

E-Mail-Ziel

Für Teams, die die Zustellung per E-Mail bevorzugen, setzen Sie destination_type auf "email":

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

Pubrio unterstützt White-Label-E-Mail-Zustellung für Agenturen und Teams. Kontaktieren Sie uns, um mehr über die Anpassung der Absenderdomain und des Brandings zu erfahren.

Fehlerbehebung

Webhook empfängt keine Payloads

Überprüfen Sie, dass Ihr Endpunkt öffentlich erreichbar ist (nicht hinter einer Firewall oder einem VPN)
Stellen Sie sicher, dass er den Statuscode 200 zurückgibt — andere Codes werden als Fehler behandelt
Verwenden Sie den Endpunkt Validate Webhook, um die Konnektivität zu testen
Prüfen Sie Statistic Logs auf Fehlermeldungen und Antwortcodes

Monitor nach Fehlern pausiert

Wenn Ihr Webhook durchgehend Nicht-200-Codes zurückgibt, pausiert der Monitor, sobald max_failure_trigger aufeinanderfolgende Fehler erreicht ist. Beheben Sie das Problem und reaktivieren Sie über Update Monitor.

Doppelte Payloads

Wenn eine Zustellung fehlschlägt und Wiederholungsversuche konfiguriert sind, können Sie denselben Payload mehrfach erhalten. Verwenden Sie triggered_at oder die Log-ID, um auf Ihrer Seite zu deduplizieren.

Payload zu groß

Reduzieren Sie max_records_per_trigger, um die Anzahl der Datensätze pro Zustellung zu begrenzen. Sie können auch Ihre Filter eingrenzen, um das Volumen übereinstimmender Signale zu reduzieren.

Monitore

Suche

Filter

Personen

Expansion

Voraussetzungen

Schritt 1: Monitor mit Webhook-Ziel erstellen

Schritt 2: Ihre Webhook-Verbindung validieren

Schritt 3: Mit echten Daten testen

Schritt 4: Signaturen verifizieren

Struktur des Webhook-Payloads

Expansion-Signale

Payload für Expansion-Signale

E-Mail-Ziel

Fehlerbehebung

​Voraussetzungen

​Schritt 1: Monitor mit Webhook-Ziel erstellen

​Schritt 2: Ihre Webhook-Verbindung validieren

​Schritt 3: Mit echten Daten testen

​Schritt 4: Signaturen verifizieren

​Struktur des Webhook-Payloads

​Expansion-Signale

​Payload für Expansion-Signale

​E-Mail-Ziel

​Fehlerbehebung

Voraussetzungen

Schritt 1: Monitor mit Webhook-Ziel erstellen

Schritt 2: Ihre Webhook-Verbindung validieren

Schritt 3: Mit echten Daten testen

Schritt 4: Signaturen verifizieren

Struktur des Webhook-Payloads

Expansion-Signale

Payload für Expansion-Signale

E-Mail-Ziel

Fehlerbehebung