Skip to main content
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

Antwort:
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.
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:
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.
Jede Lieferung trägt zwei Header: x-pubrio-signature (das oben offengelegte Geheimnis) und x-pubrio-signature-256 (Hex-HMAC-SHA256 des rohen Request-Bodys mit diesem Geheimnis als Schlüssel). Prüfen Sie den HMAC über die empfangenen Bytes, bevor Sie das JSON parsen.

Struktur des Webhook-Payloads

Payloads unterscheiden sich je nach detection_mode des Monitors:
Im Modus signal_first enthält der Payload ein signals-Array auf oberster Ebene:
Jeder Signal-Eintrag enthält die Signaldetails sowie die zugehörigen angereicherten Unternehmen und Personen.
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:
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.
Ein Webhook liefert Expansion-Signale in der Datensatzeinheit des Monitors. In der Standardeinheit signal (signal_first) ist jeder Eintrag ein Rohsignal (HIRE, AD, OFFICE…), dessen companies[0] die Karte (Unternehmen, Markt) trägt; country_code ist der Markt. Mit record_unit: "company" erhalten Sie einen Eintrag pro Unternehmen mit verschachtelten Signalen. Der E-Mail-Digest gruppiert immer pro Unternehmen und Markt.

Cloud-Footprint

DNS ist das Cloud-Footprint-Signal — ein Unternehmen baut Cloud- oder Hosting-Infrastruktur in einem Markt auf. Grenzen Sie einen Expansions-Monitor über signal_types in den Filtern darauf ein:
Jede Zustellung enthält evidence_url, eine Pubrio-Seite, die das Signal belegt. Rohe Infrastrukturdetails sind nie Teil der Nutzlast. Für dieselben Hosts als reinen Ereignisstrom mit Anbieter-, Regions- und Stadtfiltern nutzen Sie den eigenen Signaltyp cloud_footprints weiter unten.

Payload für Expansion-Signale

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.

Cloud-Footprint-Signale

Fügen Sie cloud_footprints zu signal_types hinzu, um pro Host, den ein Unternehmen in einem Markt außerhalb seines Heimatlands aufsetzt, einen Datensatz zu erhalten: ein neuer Server bei einem Cloud- oder Hosting-Anbieter oder einer, der Region oder Land gewechselt hat. Es ist derselbe Infrastruktur-Beleg, den das Expansion-Signal DNS liest, aber als reiner Ereignisstrom statt als Marktstufe geliefert: jeder Host in Eingangsreihenfolge, mit den eigenen Filtern des Footprints und ohne Stufe, Score oder Fenster.
Jedes signal trägt provider, cloud_region, city, novelty, country_code, country_name, event_date, ein lokalisiertes display_label wie AWS · Frankfurt und evidence_url. Rohe Hostnamen und IP-Adressen sind nie enthalten. Infrastruktur im Heimatmarkt ist nicht Teil dieses Stroms.

Lieferregeln

Was ein Datensatz ist

Ein Datensatz ist das, was die Limits zählen und was ein Liefereintrag ist. Standardmäßig folgt er dem Erkennungsmodus: signal_first liefert Signale (ein signals[]-Eintrag pro Stelle, Anzeige, Artikel oder Expansion-Signal), company_first liefert Unternehmen (ein companies[]-Eintrag pro Unternehmen mit verschachtelten Signalen). Mit record_unit wählen Sie explizit, z. B. liefert record_unit: "company" auf einem signal_first-Anzeigenmonitor einen Eintrag pro Werbetreibendem statt einen pro Anzeige.

Unternehmen ausschließen

excluded_companies (plus excluded_domains und excluded_linkedin_urls, aufgelöst wie companies) ist eine Niemals-liefern-Liste: Ein ausgeschlossenes Unternehmen wird in beiden Modi vor Anreicherung und Abrechnung verworfen, und eine company_first-Beobachtungsliste überspringt es, solange es auf der Liste steht. Bis zu 100.000 Unternehmen pro Monitor, genug für einen CRM-Export der Bestandskunden. Senden Sie in Update Monitor companies_mode oder excluded_companies_mode als add / remove, um nur die gesendeten Einträge zu ändern, ohne die ganze Liste erneut zu senden.

Limits

Eine Liste jeder Größe lässt sich seitenweise lesen: Company Search mit company_groups: [source_group_id] (oder excluded_group_id); beide IDs liefert Lookup Monitor, das auch die vollständigen Listen zurückgibt.

Zuerst das Neueste

Standardmäßig liefert ein Monitor in Eingangsreihenfolge, das Älteste zuerst, und ein Limit trägt den Rest vor, sodass der Rückstand eines Tages abgearbeitet wird, bevor neuere Signale kommen. Mit is_newest_first: true kehrt sich das um: Jeder Lauf liefert die neuesten passenden Datensätze, und was ein Limit auslässt, wird endgültig übersprungen, nie nachgeholt. Das gilt für jeden Signaltyp und für einen Monitor, der nach einer Pause oder einem aufgebrauchten Tagesbudget weiterläuft.

Deduplizierung und erneute Lieferung

  • Ein Signal wird nie zweimal geliefert. Jede erfolgreiche Lieferung protokolliert die Schlüssel der gelieferten Signale, und jeder Lauf verwirft Kandidaten, die bereits im Protokoll stehen, für alle Signaltypen. Stellen, News und Anzeigen führen zusätzlich einen Cursor pro Typ, sodass ein geliefertes Signal gar nicht erst erneut geholt wird.
  • company_dedupe_days: N garantiert, dass ein Unternehmen in höchstens einer Lieferung pro N Tagen über alle Signaltypen des Monitors erscheint; seine späteren Signale im Fenster werden übersprungen.
  • Jeder Payload trägt metadata.monitor_log_id (die Zeile dieses Versuchs in den Statistik-Logs) und metadata.parent_monitor_log_id (null beim ersten Versuch; bei einem Retry, automatisch oder über Process Retry, die ID des ersten Versuchs). Dieselben Signale erreichen Sie nur über einen solchen Retry erneut, deduplizieren Sie also über parent_monitor_log_id || monitor_log_id. Ein Retry sendet den Payload des ersten Versuchs unverändert; mit is_use_original_payload: false werden zuerst die heutigen Regeln (Ausschlüsse und beide Ledger) erneut angewendet, und ein Retry ohne verbleibende Datensätze wird mit Code 40085 übersprungen.

E-Mail-Ziel

Für Teams, die die Zustellung per E-Mail bevorzugen, setzen Sie destination_type auf "email":
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

  • Ü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
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.
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.
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.
Zuletzt geändert am 8. Oktober 2026