Configurando Webhooks

Webhooks são a forma recomendada de receber resultados de monitores. Quando um monitor é acionado, a Pubrio envia uma requisição POST com um payload JSON para a sua URL configurada — em tempo real.

Pré-requisitos

Uma chave de API Pubrio com acesso a monitores
Um endpoint HTTPS publicamente acessível (ou uma URL de teste do usewebhook.com)

Teste rápido: use o usewebhook.com para gerar uma URL de webhook temporária e gratuita. Você pode inspecionar cada payload recebido sem precisar implantar nada.

Etapa 1: Criar um Monitor com Destino de 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());

Resposta:

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

O objeto headers adiciona cabeçalhos HTTP personalizados a cada entrega (útil para autenticação). O objeto body adiciona campos personalizados à raiz do payload do webhook.

Salve o signature retornado na resposta — você vai precisar dele para verificar os payloads recebidos. Ele só é retornado no momento da criação, pelo endpoint Signature Reveal, ou pelo Monitor Lookup com is_signature_reveal: true.

Etapa 2: Validar a Conexão do Webhook

Use o endpoint Validate Webhook para testar se o seu endpoint está acessível. Isso envia um payload de amostra com dados fictícios — nenhum crédito é consumido e nenhum sinal real é buscado.

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

Uma resposta bem-sucedida retorna o payload de amostra que foi enviado e a resposta que o seu endpoint devolveu — assim você confirma que a conexão funciona antes de colocar em produção.

Etapa 3: Testar com Dados Reais

Depois que a conexão for validada, acione uma execução real usando o endpoint Process Try. Isso busca sinais reais e os entrega ao seu webhook — use tried_at com uma data recente no passado para garantir que haja dados disponíveis:

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

Ao contrário do validate, o endpoint try executa uma varredura real e consome créditos. Use-o para confirmar que os payloads reais chegam corretamente e para ter uma estimativa rápida dos resultados antes que a varredura agendada seja executada.

Etapa 4: Verificar Assinaturas

Cada monitor tem uma assinatura única para verificar que os payloads recebidos vêm de fato da 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"
  }
}

Cada entrega traz dois cabeçalhos: x-pubrio-signature (o segredo revelado acima) e x-pubrio-signature-256 (HMAC-SHA256 em hexadecimal do corpo bruto da requisição, com esse segredo como chave). Verifique o HMAC sobre os bytes recebidos antes de fazer o parse do JSON.

Estrutura do Payload do Webhook

Os payloads variam de acordo com o detection_mode do monitor:

Sinal Primeiro
Empresa Primeiro

No modo signal_first, o payload contém um array signals no nível raiz:

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

Cada entrada de sinal contém os detalhes do sinal e as empresas e pessoas enriquecidas associadas.

No modo company_first, o payload contém um array companies no nível raiz, com dados de empresa enriquecidos e sinais aninhados:

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

Cada empresa no array inclui o perfil enriquecido completo, todos os sinais correspondentes e os contatos de pessoas enriquecidos.

Os campos personalizados de body definidos em destination_config aparecem no nível raiz do payload (por exemplo, "pipeline": "my-webhook" quando configurado no seu destino).

Sinais de Expansão

Além de jobs, news e advertisements, um monitor pode observar sinais de expansão — a evidência datada de que uma empresa está entrando ou crescendo em um novo mercado. Adicione expansions a 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"
  }
}

Os filtros de expansão usam o vocabulário do Expansion Search, e não o de vagas/notícias/anúncios — froms e tos para o corredor, além de stages, scopes, momentum, freshness, signal_types, signal_subtypes, signal_strengths, source_types e window_days. Resolva os slugs válidos em Expansion Reference.

Um webhook entrega sinais de expansão na unidade de registro do monitor. Na unidade padrão signal (signal_first), cada entrada é um sinal bruto (HIRE, AD, OFFICE…) cujo companies[0] traz o cartão (empresa, mercado); country_code é o mercado. Defina record_unit: "company" para receber uma entrada por empresa com seus sinais aninhados. O resumo por e-mail sempre agrupa por empresa e mercado.

Pegada cloud

DNS é o sinal de pegada cloud: uma empresa a implementar infraestrutura cloud ou de alojamento num mercado. Restrinja um monitor de expansão com signal_types dentro dos filtros:

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

Cada entrega inclui evidence_url, uma página Pubrio que sustenta o sinal. O detalhe bruto da infraestrutura nunca é incluído. Para receber os mesmos hosts como um fluxo de eventos simples com filtros de provedor, região e cidade, use o tipo de sinal dedicado cloud_footprints abaixo.

Payload de Sinal de Expansão

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

O significado de cada campo está detalhado na Expansion Field Reference. Para obter as mesmas linhas sob demanda em vez de por acionamento, use o Expansion Signal Search.

Sinais de pegada em nuvem

Adicione cloud_footprints a signal_types para receber um registro por host que uma empresa sobe em um mercado fora do seu país: um servidor novo em um provedor de nuvem ou hospedagem, ou um que mudou de região ou de país. É a mesma evidência de infraestrutura que o sinal de expansão DNS lê, entregue como um fluxo de eventos simples em vez de uma etapa de mercado: cada host, na ordem de chegada, com os filtros próprios da pegada e sem etapa, pontuação ou janela.

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

Filtro	Significado
`providers` / `exclude_providers`	Provedor de nuvem ou hospedagem, com o nome usado no Cloud Footprint Search
`cloud_regions` / `exclude_cloud_regions`	Códigos de região do provedor, p. ex. `eu-central-1`
`cities` / `exclude_cities`	Cidades dos data centers
`country_codes`	País onde o host está

Cada signal traz provider, cloud_region, city, novelty, country_code, country_name, event_date, um display_label localizado como AWS · Frankfurt e evidence_url. Nomes de host e endereços IP brutos nunca são incluídos. A infraestrutura do mercado doméstico não está neste fluxo.

Regras de Entrega

O que é um registro

Um registro é o que os limites contam e o que constitui uma entrada de entrega. Por padrão segue o modo de detecção: signal_first entrega sinais (uma entrada signals[] por vaga, anúncio, artigo ou sinal de expansão), company_first entrega empresas (uma entrada companies[] por empresa com seus sinais aninhados). Use record_unit para escolher explicitamente; por exemplo, record_unit: "company" em um monitor de anúncios signal_first entrega uma entrada por anunciante em vez de uma por anúncio.

Excluir empresas

excluded_companies (mais excluded_domains e excluded_linkedin_urls, resolvidos como companies) é uma lista de nunca entregar: uma empresa excluída é descartada antes do enriquecimento e da faturação em ambos os modos, e a lista de acompanhamento company_first a ignora enquanto permanecer na lista. Até 100.000 empresas por monitor, o suficiente para uma exportação de clientes atuais do CRM. No Update Monitor, envie companies_mode ou excluded_companies_mode como add / remove para alterar apenas as entradas enviadas, sem reenviar a lista inteira.

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

Limites

Parâmetro	Conta	Comportamento
`max_records_per_trigger`	registros em uma entrega	O restante é transportado: vagas, notícias e anúncios mantêm um cursor por tipo, então o próximo disparo continua de onde este parou. Sinais de expansão usam uma janela de datas que recomeça no registro mais antigo que o limite deixou de fora, então o excedente deles também é transportado.
`max_daily_trigger`	entregas bem-sucedidas não vazias por dia civil (fuso do proprietário)	Um disparo vazio (sem sinal correspondente) e uma entrega com falha não contam.
`max_daily_records`	registros por dia civil (fuso do proprietário)	Limite rígido: um disparo entrega no máximo o orçamento restante e depois o monitor aguarda o dia seguinte sem mover seu cursor.

Uma lista de qualquer tamanho é lida página a página: Company Search com company_groups: [source_group_id] (ou excluded_group_id); ambos os ids são devolvidos por Lookup Monitor, que também devolve as listas completas.

O mais recente primeiro

Por padrão, um monitor entrega por ordem de chegada, o mais antigo primeiro, e um limite transporta o restante, de modo que o atraso de um dia é processado antes dos sinais mais novos. Com is_newest_first: true isso se inverte: cada execução entrega os registros correspondentes mais recentes, e o que um limite deixa de fora é ignorado de vez, nunca enfileirado. Vale para todos os tipos de sinal e para um monitor que retoma após uma pausa ou um orçamento diário esgotado.

Deduplicação e reentrega

Um sinal nunca é entregue duas vezes. Cada entrega bem-sucedida registra as chaves dos sinais que carregou, e cada execução descarta qualquer candidato já presente nesse registro, para todos os tipos de sinal. Vagas, notícias e anúncios mantêm ainda um cursor por tipo, então um sinal entregue nem sequer é buscado de novo.
company_dedupe_days: N garante que uma empresa apareça em no máximo uma entrega a cada N dias em todos os tipos de sinal do monitor; seus sinais seguintes dentro da janela são ignorados.
Todo payload carrega metadata.monitor_log_id (a linha dessa tentativa nos Logs de Estatísticas) e metadata.parent_monitor_log_id (null na primeira tentativa; em uma nova tentativa, automática ou via Repetir Processamento, o id da primeira tentativa). Os mesmos sinais só voltam a chegar por meio dessa nova tentativa, então deduplique por parent_monitor_log_id || monitor_log_id. Uma nova tentativa reenvia o payload da primeira tentativa como estava; envie is_use_original_payload: false para reaplicar primeiro as regras atuais (exclusões e os dois registros), e então uma tentativa sem nada a entregar é ignorada com o código 40085.

Destino por E-mail

Para equipes que preferem a entrega por e-mail, defina destination_type como "email":

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

A Pubrio oferece suporte a entrega de e-mail com marca branca para agências e equipes. Entre em contato para saber mais sobre personalização de domínio de envio e identidade visual.

Solução de Problemas

O webhook não recebe payloads

Verifique se o seu endpoint é publicamente acessível (não está atrás de um firewall ou VPN)
Garanta que ele retorne um código de status 200 — outros códigos são tratados como falhas
Use o endpoint Validate Webhook para testar a conectividade
Verifique os Statistic Logs em busca de mensagens de erro e códigos de resposta

Monitor pausado após falhas

Se o seu webhook retornar códigos diferentes de 200 de forma consistente, o monitor é pausado ao atingir max_failure_trigger falhas consecutivas. Corrija o problema e reative usando o Update Monitor.

Payloads duplicados

Se uma entrega falhar e houver novas tentativas configuradas, você pode receber o mesmo payload várias vezes. Use triggered_at ou o ID do log para deduplicar do seu lado.

Payload muito grande

Reduza max_records_per_trigger para limitar os registros por entrega. Você também pode restringir seus filtros para reduzir o volume de sinais correspondentes.

Monitoramento

Busca

Filtros

Pessoas

Expansão

Pré-requisitos

Etapa 1: Criar um Monitor com Destino de Webhook

Etapa 2: Validar a Conexão do Webhook

Etapa 3: Testar com Dados Reais

Etapa 4: Verificar Assinaturas

Estrutura do Payload do Webhook

Sinais de Expansão

Pegada cloud

Payload de Sinal de Expansão

Sinais de pegada em nuvem

Regras de Entrega

O que é um registro

Excluir empresas

Limites

O mais recente primeiro

Deduplicação e reentrega

Destino por E-mail

Solução de Problemas

​Pré-requisitos

​Etapa 1: Criar um Monitor com Destino de Webhook

​Etapa 2: Validar a Conexão do Webhook

​Etapa 3: Testar com Dados Reais

​Etapa 4: Verificar Assinaturas

​Estrutura do Payload do Webhook

​Sinais de Expansão

​Pegada cloud

​Payload de Sinal de Expansão

​Sinais de pegada em nuvem

​Regras de Entrega

​O que é um registro

​Excluir empresas

​Limites

​O mais recente primeiro

​Deduplicação e reentrega

​Destino por E-mail

​Solução de Problemas

Pré-requisitos

Etapa 1: Criar um Monitor com Destino de Webhook

Etapa 2: Validar a Conexão do Webhook

Etapa 3: Testar com Dados Reais

Etapa 4: Verificar Assinaturas

Estrutura do Payload do Webhook

Sinais de Expansão

Pegada cloud

Payload de Sinal de Expansão

Sinais de pegada em nuvem

Regras de Entrega

O que é um registro

Excluir empresas

Limites

O mais recente primeiro

Deduplicação e reentrega

Destino por E-mail

Solução de Problemas