Configurer des webhooks

Les webhooks sont le moyen recommandé pour recevoir les résultats d’un monitor. Lorsqu’un monitor se déclenche, Pubrio envoie une requête POST avec une charge utile JSON à l’URL que vous avez configurée — en temps réel.

Prérequis

Une clé API Pubrio avec accès aux monitors
Un point de terminaison HTTPS accessible publiquement (ou une URL de test depuis usewebhook.com)

Test rapide : utilisez usewebhook.com pour générer une URL de webhook temporaire et gratuite. Vous pouvez inspecter chaque charge utile entrante sans rien déployer.

Étape 1 : créer un Monitor avec une destination webhook

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

Réponse :

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

L’objet headers ajoute des en-têtes HTTP personnalisés à chaque envoi (utile pour l’authentification). L’objet body ajoute des champs personnalisés à la racine de la charge utile du webhook.

Conservez le signature renvoyé dans la réponse — vous en aurez besoin pour vérifier les charges utiles entrantes. Il n’est renvoyé qu’à la création, via le point de terminaison Signature Reveal, ou depuis Monitor Lookup avec is_signature_reveal: true.

Étape 2 : valider votre connexion webhook

Utilisez le point de terminaison Validate Webhook pour tester que votre point de terminaison est joignable. Cela envoie une charge utile d’exemple avec des données de substitution — aucun crédit n’est consommé, aucun signal réel n’est récupéré.

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

Une réponse réussie renvoie la charge utile d’exemple qui a été envoyée et la réponse que votre point de terminaison a retournée — pour que vous puissiez confirmer que la connexion fonctionne avant de passer en production.

Étape 3 : tester avec des données réelles

Une fois la connexion validée, déclenchez une exécution réelle avec le point de terminaison Process Try. Cela récupère de vrais signaux et les livre à votre webhook — utilisez tried_at avec une date passée récente pour vous assurer que des données sont disponibles :

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

Contrairement à validate, le point de terminaison try exécute un vrai scan et consomme des crédits. Utilisez-le pour vérifier que les charges utiles réelles arrivent correctement et obtenir une estimation rapide des résultats avant le déclenchement du scan planifié.

Étape 4 : vérifier les signatures

Chaque monitor dispose d’une signature unique permettant de vérifier que les charges utiles entrantes proviennent bien de 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"
  }
}

Chaque livraison porte deux en-têtes : x-pubrio-signature (le secret révélé ci-dessus) et x-pubrio-signature-256 (HMAC-SHA256 hexadécimal du corps brut de la requête, avec ce secret comme clé). Vérifiez le HMAC sur les octets reçus avant de parser le JSON.

Structure de la charge utile du webhook

Les charges utiles diffèrent selon le detection_mode du monitor :

Signal First
Company First

En mode signal_first, la charge utile contient un tableau signals de premier niveau :

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

Chaque entrée de signal contient les détails du signal ainsi que les entreprises et personnes enrichies associées.

En mode company_first, la charge utile contient un tableau companies de premier niveau, avec des données d’entreprise enrichies et des signaux imbriqués :

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

Chaque entreprise du tableau inclut le profil enrichi complet, tous les signaux correspondants, et les contacts de personnes enrichis.

Les champs body personnalisés issus de destination_config apparaissent à la racine de la charge utile (par exemple, "pipeline": "my-webhook" s’il est configuré dans votre destination).

Signaux d’expansion

Aux côtés de jobs, news et advertisements, un monitor peut surveiller les signaux d’expansion — la preuve datée qu’une entreprise entre sur un nouveau marché ou s’y développe. Ajoutez expansions à 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"
  }
}

Les filtres d’expansion utilisent le vocabulaire de Expansion Search, et non celui des offres d’emploi/actualités/publicités — froms et tos pour le corridor, plus stages, scopes, momentum, freshness, signal_types, signal_subtypes, signal_strengths, source_types et window_days. Résolvez les slugs valides depuis Expansion Reference.

Un webhook livre les signaux d’expansion dans l’unité d’enregistrement du moniteur. Dans l’unité signal par défaut (signal_first), chaque entrée est un signal brut (HIRE, AD, OFFICE…) dont companies[0] porte la fiche (entreprise, marché) ; country_code est le marché. Définissez record_unit: "company" pour recevoir une entrée par entreprise avec ses signaux imbriqués. Le digest e-mail regroupe toujours par entreprise et marché.

Empreinte cloud

DNS est le signal d’empreinte cloud : une entreprise qui déploie de l’infrastructure cloud ou d’hébergement sur un marché. Restreignez un monitor d’expansion via signal_types dans les filtres :

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

Chaque livraison contient evidence_url, une page Pubrio qui étaye le signal. Le détail brut de l’infrastructure n’est jamais inclus. Pour recevoir les mêmes hôtes sous forme de flux d’événements avec des filtres par fournisseur, région et ville, utilisez le type de signal dédié cloud_footprints ci-dessous.

Charge utile des signaux d’expansion

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

La signification de chaque champ figure dans la Référence des champs d’expansion. Pour récupérer les mêmes lignes à la demande plutôt que via un déclencheur, utilisez Expansion Signal Search.

Signaux d’empreinte cloud

Ajoutez cloud_footprints à signal_types pour recevoir un enregistrement par hôte qu’une entreprise met en place sur un marché hors de son pays : un nouveau serveur chez un fournisseur cloud ou d’hébergement, ou un serveur qui a changé de région ou de pays. C’est la même preuve d’infrastructure que lit le signal d’expansion DNS, livrée comme un simple flux d’événements plutôt qu’une étape de marché : chaque hôte, dans l’ordre d’arrivée, avec les filtres propres à l’empreinte, sans étape, score ni fenêtre.

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

Filtre	Signification
`providers` / `exclude_providers`	Fournisseur cloud ou d’hébergement, nommé comme dans Cloud Footprint Search
`cloud_regions` / `exclude_cloud_regions`	Codes de région du fournisseur, par ex. `eu-central-1`
`cities` / `exclude_cities`	Villes des centres de données
`country_codes`	Pays où se trouve l’hôte

Chaque signal porte provider, cloud_region, city, novelty, country_code, country_name, event_date, un display_label localisé comme AWS · Frankfurt et evidence_url. Les noms d’hôte et adresses IP bruts ne sont jamais inclus. L’infrastructure du marché domestique ne fait pas partie de ce flux.

Règles de livraison

Ce qu’est un enregistrement

Un enregistrement est ce que comptent les plafonds et ce que constitue une entrée de livraison. Par défaut il suit le mode de détection : signal_first livre des signaux (une entrée signals[] par offre, annonce, article ou signal d’expansion), company_first livre des entreprises (une entrée companies[] par entreprise avec ses signaux imbriqués). Utilisez record_unit pour choisir explicitement ; par exemple record_unit: "company" sur un moniteur d’annonces signal_first livre une entrée par annonceur au lieu d’une par annonce.

Exclure des entreprises

excluded_companies (plus excluded_domains et excluded_linkedin_urls, résolus comme companies) est une liste à ne jamais livrer : une entreprise exclue est écartée avant l’enrichissement et la facturation dans les deux modes, et une liste de suivi company_first l’ignore tant qu’elle reste sur la liste. Jusqu’à 100 000 entreprises par moniteur, de quoi accueillir un export CRM des clients existants. Dans Update Monitor, envoyez companies_mode ou excluded_companies_mode à add / remove pour ne modifier que les entrées envoyées, sans renvoyer toute la liste.

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

Plafonds

Paramètre	Compte	Comportement
`max_records_per_trigger`	enregistrements dans une livraison	Le reste est reporté : offres, actualités et annonces conservent un curseur par type, le déclenchement suivant reprend là où celui-ci s’est arrêté. Les signaux d’expansion utilisent une fenêtre de dates qui redémarre à l’enregistrement le plus ancien laissé de côté par le plafond, de sorte que leur surplus est lui aussi reporté.
`max_daily_trigger`	livraisons réussies non vides par jour civil (fuseau du propriétaire)	Un déclenchement vide (aucun signal) et une livraison échouée ne comptent pas.
`max_daily_records`	enregistrements par jour civil (fuseau du propriétaire)	Plafond strict : un déclenchement livre au plus le budget restant, puis le moniteur attend le lendemain sans déplacer son curseur.

Une liste de n’importe quelle taille se lit page par page : Company Search avec company_groups: [source_group_id] (ou excluded_group_id) ; les deux ids sont renvoyés par Lookup Monitor, qui renvoie aussi les listes complètes.

Le plus récent d’abord

Par défaut, un monitor livre dans l’ordre d’arrivée, le plus ancien d’abord, et un plafond reporte le reste : le retard d’une journée est traité avant les signaux plus récents. Avec is_newest_first: true, c’est l’inverse : chaque exécution livre les enregistrements les plus récents, et ce qu’un plafond laisse de côté est ignoré définitivement, jamais mis en file d’attente. Cela vaut pour chaque type de signal et pour un monitor qui reprend après une pause ou un budget quotidien épuisé.

Déduplication et nouvelle livraison

Un signal n’est jamais livré deux fois. Chaque livraison réussie journalise les clés des signaux qu’elle portait, et chaque exécution écarte tout candidat déjà présent dans ce journal, pour tous les types de signaux. Offres, actualités et annonces conservent en plus un curseur par type, donc un signal livré n’est même pas récupéré à nouveau.
company_dedupe_days: N garantit qu’une entreprise apparaît dans au plus une livraison par N jours, tous types de signaux du moniteur confondus ; ses signaux suivants dans la fenêtre sont ignorés.
Chaque payload porte metadata.monitor_log_id (la ligne de cette tentative dans les Journaux statistiques) et metadata.parent_monitor_log_id (null à la première tentative ; lors d’une nouvelle tentative, automatique ou via Relancer le traitement, l’id de la première tentative). Les mêmes signaux ne peuvent vous revenir que par une telle tentative ; dédupliquez donc sur parent_monitor_log_id || monitor_log_id. Une relance renvoie le payload de la première tentative tel quel ; envoyez is_use_original_payload: false pour réappliquer d’abord les règles actuelles (exclusions et les deux registres), auquel cas une relance sans rien à livrer est ignorée avec le code 40085.

Destination e-mail

Pour les équipes qui préfèrent la livraison par e-mail, définissez destination_type sur "email" :

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

Pubrio prend en charge la livraison d’e-mails en marque blanche pour les agences et les équipes. Contactez-nous pour en savoir plus sur la personnalisation du domaine expéditeur et de l’image de marque.

Dépannage

Le webhook ne reçoit pas de charges utiles

Vérifiez que votre point de terminaison est accessible publiquement (pas derrière un pare-feu ou un VPN)
Assurez-vous qu’il renvoie un code de statut 200 — les autres codes sont traités comme des échecs
Utilisez le point de terminaison Validate Webhook pour tester la connectivité
Consultez les Statistic Logs pour les messages d’erreur et les codes de réponse

Monitor mis en pause après des échecs

Si votre webhook renvoie systématiquement des codes non-200, le monitor se met en pause après avoir atteint max_failure_trigger échecs consécutifs. Corrigez le problème puis réactivez via Update Monitor.

Charges utiles en double

Si une livraison échoue et que des tentatives sont configurées, vous pouvez recevoir plusieurs fois la même charge utile. Utilisez triggered_at ou l’identifiant de journal pour dédupliquer de votre côté.

Charge utile trop volumineuse

Réduisez max_records_per_trigger pour limiter le nombre d’enregistrements par livraison. Vous pouvez aussi restreindre vos filtres pour réduire le volume de signaux correspondants.

Monitor

Recherche

Filtres

Personnes

Expansion

Prérequis

Étape 1 : créer un Monitor avec une destination webhook

Étape 2 : valider votre connexion webhook

Étape 3 : tester avec des données réelles

Étape 4 : vérifier les signatures

Structure de la charge utile du webhook

Signaux d’expansion

Empreinte cloud

Charge utile des signaux d’expansion

Signaux d’empreinte cloud

Règles de livraison

Ce qu’est un enregistrement

Exclure des entreprises

Plafonds

Le plus récent d’abord

Déduplication et nouvelle livraison

Destination e-mail

Dépannage

​Prérequis

​Étape 1 : créer un Monitor avec une destination webhook

​Étape 2 : valider votre connexion webhook

​Étape 3 : tester avec des données réelles

​Étape 4 : vérifier les signatures

​Structure de la charge utile du webhook

​Signaux d’expansion

​Empreinte cloud

​Charge utile des signaux d’expansion

​Signaux d’empreinte cloud

​Règles de livraison

​Ce qu’est un enregistrement

​Exclure des entreprises

​Plafonds

​Le plus récent d’abord

​Déduplication et nouvelle livraison

​Destination e-mail

​Dépannage

Prérequis

Étape 1 : créer un Monitor avec une destination webhook

Étape 2 : valider votre connexion webhook

Étape 3 : tester avec des données réelles

Étape 4 : vérifier les signatures

Structure de la charge utile du webhook

Signaux d’expansion

Empreinte cloud

Charge utile des signaux d’expansion

Signaux d’empreinte cloud

Règles de livraison

Ce qu’est un enregistrement

Exclure des entreprises

Plafonds

Le plus récent d’abord

Déduplication et nouvelle livraison

Destination e-mail

Dépannage