Webhook 설정

Webhook은 모니터 결과를 수신하는 권장 방법입니다. 모니터가 트리거되면, Pubrio가 구성된 URL로 JSON 페이로드를 포함한 POST 요청을 실시간으로 전송합니다.

사전 요구 사항

모니터 접근 권한이 있는 Pubrio API 키
공개적으로 접근 가능한 HTTPS 엔드포인트(또는 usewebhook.com의 테스트 URL)

빠른 테스트: usewebhook.com을 사용하여 무료 임시 webhook URL을 생성하세요. 아무것도 배포하지 않고 모든 수신 페이로드를 확인할 수 있습니다.

1단계: 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());

응답:

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

headers 객체는 매 전달마다 커스텀 HTTP 헤더를 추가합니다(인증에 유용). body 객체는 webhook 페이로드의 루트 레벨에 커스텀 필드를 추가합니다.

응답의 signature를 저장하세요 — 수신 페이로드를 검증하는 데 필요합니다. 이것은 생성 시, 서명 공개 엔드포인트, 또는 is_signature_reveal: true를 사용한 모니터 조회를 통해서만 반환됩니다.

2단계: Webhook 연결 검증

Webhook 검증 엔드포인트를 사용하여 엔드포인트가 도달 가능한지 테스트합니다. 이것은 플레이스홀더 데이터가 포함된 샘플 페이로드를 전송합니다 — 크레딧이 소비되지 않고, 실제 신호도 가져오지 않습니다.

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

성공적인 응답은 전송된 샘플 요청 페이로드와 엔드포인트가 반환한 응답을 포함합니다 — 이를 통해 라이브 전환 전에 연결이 정상임을 확인할 수 있습니다.

3단계: 실제 데이터로 테스트

연결이 검증되면, 프로세스 트라이 엔드포인트를 사용하여 실제 실행을 트리거합니다. 이것은 실제 신호를 가져와 webhook으로 전달합니다 — tried_at에 최근 과거 날짜를 사용하여 데이터가 있는지 확인하세요:

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

validate와 달리, try 엔드포인트는 실제 스캔을 실행하고 크레딧을 소비합니다. 실제 페이로드가 올바르게 도착하는지 확인하고, 예약된 스캔이 시작되기 전에 결과를 빠르게 추정하는 데 사용하세요.

4단계: 서명 검증

각 모니터에는 수신 페이로드가 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"
  }
}

모든 전달에는 두 헤더가 붙습니다: x-pubrio-signature(위에서 확인한 시크릿)와 x-pubrio-signature-256(그 시크릿을 키로 한 원시 요청 본문의 16진 HMAC-SHA256). JSON을 파싱하기 전에 받은 원시 바이트로 HMAC을 검증하세요.

Webhook 페이로드 구조

페이로드는 모니터의 detection_mode에 따라 다릅니다:

신호 우선
기업 우선

signal_first 모드에서는 페이로드에 최상위 signals 배열이 포함됩니다:

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

각 신호 항목에는 신호 세부 정보와 관련된 보강 기업 및 인물이 포함됩니다.

company_first 모드에서는 페이로드에 보강된 기업 데이터와 중첩된 신호가 포함된 최상위 companies 배열이 있습니다:

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

배열의 각 기업에는 전체 보강 프로필, 모든 매칭 신호, 보강된 인물 연락처가 포함됩니다.

destination_config의 커스텀 body 필드는 페이로드의 루트 레벨에 병합됩니다. 이를 사용하여 내부 라우팅 또는 태깅을 위한 정적 메타데이터를 추가하세요(예: "pipeline": "my-webhook").

확장 신호

jobs, news, advertisements 외에도 모니터는 확장 신호 — 기업이 새로운 시장에 진입하거나 성장하고 있음을 보여주는 날짜가 지정된 증거 — 를 감시할 수 있습니다. signal_types에 expansions를 추가하기만 하면 됩니다.

{
  "name": "미국 시장 진입",
  "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 Search의 어휘를 사용합니다. 코리도를 지정하는 froms와 tos 외에 stages, scopes, momentum, freshness, signal_types, signal_subtypes, signal_strengths, source_types, window_days가 있습니다. 유효한 슬러그는 Expansion Reference에서 확인하세요.

웹훅은 모니터의 레코드 단위로 확장 신호를 전달합니다. 기본 signal 단위(signal_first)에서는 각 항목이 원시 신호 하나(HIRE, AD, OFFICE…)이며 companies[0]이 (기업, 시장) 카드를 담고 country_code가 시장입니다. record_unit: "company"로 설정하면 기업당 한 항목에 신호가 중첩됩니다. 이메일 다이제스트는 항상 기업과 시장별로 그룹화됩니다.

클라우드 풋프린트

DNS는 클라우드 풋프린트 시그널로, 기업이 특정 시장에 클라우드·호스팅 인프라를 구축하는 것을 뜻합니다. 확장 필터의 signal_types로 모니터를 좁히세요.

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

모든 전송에는 시그널을 뒷받침하는 Pubrio 페이지 링크 evidence_url이 포함됩니다. 원시 인프라 정보는 페이로드에 포함되지 않습니다. 같은 호스트를 제공사·리전·도시 필터가 있는 순수 이벤트 스트림으로 받으려면 아래 전용 시그널 유형 cloud_footprints를 사용하세요.

확장 신호 페이로드

{
  "monitor": {
    "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "미국 시장 진입",
    "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": [...]
    }
  ]
}

각 필드의 의미는 확장 필드 레퍼런스를 참조하세요. 트리거가 아니라 필요할 때 동일한 행을 조회하려면 Expansion Signal Search를 사용하세요.

클라우드 풋프린트 시그널

signal_types에 cloud_footprints를 추가하면 회사가 본국 밖 시장에 올린 호스트마다 레코드 하나를 받습니다. 클라우드나 호스팅 제공사의 새 서버이거나, 리전 또는 국가를 옮긴 서버입니다. 확장 시그널의 DNS가 읽는 것과 같은 인프라 근거이지만, 시장 단계가 아니라 순수 이벤트 스트림으로 전달됩니다. 모든 호스트를 도착 순서대로, 풋프린트 고유의 필터로, 단계·점수·창 없이 보냅니다.

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

필터	의미
`providers` / `exclude_providers`	Cloud Footprint Search와 같은 이름의 클라우드/호스팅 제공사
`cloud_regions` / `exclude_cloud_regions`	제공사 리전 코드(예: `eu-central-1`)
`cities` / `exclude_cities`	데이터센터 도시
`country_codes`	호스트가 있는 국가

각 signal에는 provider, cloud_region, city, novelty, country_code, country_name, event_date, 현지화된 display_label(예: AWS · Frankfurt), evidence_url이 담깁니다. 원시 호스트명과 IP 주소는 절대 포함되지 않습니다. 본국 시장의 인프라는 이 스트림에 없습니다.

전달 규칙

레코드란

레코드는 상한이 세는 단위이자 전달 항목 하나입니다. 기본값은 감지 모드를 따릅니다: signal_first는 시그널을 전달(채용·광고·기사·확장 신호당 signals[] 1건), company_first는 기업을 전달(기업당 companies[] 1건, 시그널은 중첩). record_unit으로 명시적으로 고를 수 있습니다. 예를 들어 signal_first 광고 모니터에 record_unit: "company"를 설정하면 광고당이 아니라 광고주당 한 항목이 전달됩니다.

기업 제외

excluded_companies(그리고 companies와 같은 방식으로 해석되는 excluded_domains, excluded_linkedin_urls)는 절대 전달하지 않는 목록입니다. 제외된 기업은 두 감지 모드 모두에서 보강과 과금 전에 제거되고, company_first 관심 목록도 목록에 있는 동안 해당 기업을 건너뜁니다. 모니터당 최대 100,000개로, 기존 고객의 CRM 내보내기를 담을 수 있습니다. Update Monitor에서 companies_mode 또는 excluded_companies_mode를 add / remove로 보내면 보낸 항목만 바뀌므로 전체 목록을 다시 보낼 필요가 없습니다.

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

상한

매개변수	세는 대상	동작
`max_records_per_trigger`	한 번의 전달 안의 레코드 수	나머지는 이월됩니다: 채용·뉴스·광고는 유형별 커서를 유지하므로 다음 트리거가 이번에 멈춘 곳에서 이어집니다. 확장 신호는 날짜 창으로 읽지만, 창이 상한에서 밀린 가장 오래된 레코드부터 다시 시작하므로 초과분도 이월됩니다.
`max_daily_trigger`	달력일당 비어 있지 않은 성공 전달 수(소유자 시간대)	빈 트리거(일치 신호 없음)와 전달 실패는 세지 않습니다.
`max_daily_records`	달력일당 레코드 수(소유자 시간대)	하드 리밋: 한 번의 트리거는 남은 예산까지만 전달하고, 이후 모니터는 커서를 옮기지 않고 다음 날까지 기다립니다.

어떤 크기의 목록이든 페이지 단위로 읽을 수 있습니다. Company Search에 company_groups: [source_group_id](또는 excluded_group_id)를 보내세요. 두 ID 모두 Lookup Monitor가 돌려주며, 이 엔드포인트는 전체 목록도 돌려줍니다.

중복 제거와 재전달

시그널은 두 번 전달되지 않습니다. 성공한 전달마다 실린 시그널 키를 기록하고, 모든 실행은 기록에 이미 있는 후보를 모든 시그널 유형에서 버립니다. 채용·뉴스·광고는 유형별 커서도 유지하므로 전달된 시그널은 다시 가져오지도 않습니다.
company_dedupe_days: N은 같은 기업이 N일 동안 최대 한 번의 전달에만 나타나도록 보장합니다(모니터의 모든 시그널 유형에 걸쳐). 기간 안의 이후 시그널은 건너뜁니다.
모든 페이로드에는 metadata.monitor_log_id(해당 시도의 통계 로그 행)와 metadata.parent_monitor_log_id(첫 시도는 null, 재시도는 자동이든 재시도 처리든 첫 시도의 ID)가 있습니다. 같은 시그널은 이런 재시도로만 다시 도착하므로 parent_monitor_log_id || monitor_log_id로 중복을 제거하세요. 재시도는 기본적으로 첫 시도의 페이로드를 그대로 다시 보냅니다. is_use_original_payload: false를 보내면 먼저 현재 규칙(제외 목록과 두 원장)을 다시 적용하고, 남는 것이 없으면 코드 40085로 건너뜁니다.

이메일 전달 대상

이메일 전달을 선호하는 팀은 destination_type을 "email"로 설정하세요:

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

Pubrio는 에이전시와 팀을 위한 화이트 라벨 이메일 전달을 지원합니다. 발신자 도메인 및 브랜딩 커스터마이징에 대해 문의하기에서 알아보세요.

문제 해결

Webhook이 페이로드를 수신하지 않음

엔드포인트가 공개적으로 접근 가능한지 확인하세요(방화벽이나 VPN 뒤에 있지 않은지)
200 상태 코드를 반환하는지 확인하세요 — 다른 코드는 실패로 처리됩니다
Webhook 검증 엔드포인트를 사용하여 연결을 테스트하세요
통계 로그에서 오류 메시지와 응답 코드를 확인하세요

실패 후 모니터 일시 중지

webhook이 지속적으로 200이 아닌 코드를 반환하면, max_failure_trigger 연속 실패 횟수에 도달한 후 모니터가 일시 중지됩니다. 문제를 수정하고 모니터 업데이트를 통해 다시 활성화하세요.

중복 페이로드

전달이 실패하고 재시도가 구성된 경우, 동일한 페이로드를 여러 번 수신할 수 있습니다. triggered_at 또는 로그 ID를 사용하여 중복을 제거하세요.

페이로드가 너무 큼

max_records_per_trigger를 줄여 전달당 레코드 수를 제한하세요. 필터를 좁혀 매칭되는 신호 볼륨을 줄일 수도 있습니다.

모니터

검색

필터

인물

확장

사전 요구 사항

1단계: Webhook 전달 대상으로 모니터 생성

2단계: Webhook 연결 검증

3단계: 실제 데이터로 테스트

4단계: 서명 검증

Webhook 페이로드 구조

확장 신호

클라우드 풋프린트

확장 신호 페이로드

클라우드 풋프린트 시그널

전달 규칙

레코드란

기업 제외

상한

최신 우선

중복 제거와 재전달

이메일 전달 대상

문제 해결

​사전 요구 사항

​1단계: Webhook 전달 대상으로 모니터 생성

​2단계: Webhook 연결 검증

​3단계: 실제 데이터로 테스트

​4단계: 서명 검증

​Webhook 페이로드 구조

​확장 신호

​클라우드 풋프린트

​확장 신호 페이로드

​클라우드 풋프린트 시그널

​전달 규칙

​레코드란

​기업 제외

​상한

​최신 우선

​중복 제거와 재전달

​이메일 전달 대상

​문제 해결

사전 요구 사항

1단계: Webhook 전달 대상으로 모니터 생성

2단계: Webhook 연결 검증

3단계: 실제 데이터로 테스트

4단계: 서명 검증

Webhook 페이로드 구조

확장 신호

클라우드 풋프린트

확장 신호 페이로드

클라우드 풋프린트 시그널

전달 규칙

레코드란

기업 제외

상한

최신 우선

중복 제거와 재전달

이메일 전달 대상

문제 해결