웹훅

웹훅을 사용하면 링크가 클릭될 때와 생성, 업데이트, 삭제될 때를 포함하여 링크에 대한 실시간 알림을 받을 수 있습니다. Linkly는 각 이벤트에 대한 자세한 정보를 포함하여 지정된 URL에 POST 요청을 보냅니다.

사용 사례

  • 자동화 플랫폼: 링크가 클릭될 때 Make 또는 Zapier에서 워크플로우 트리거
  • 사용자 정의 분석: 클릭 데이터를 자신의 분석 시스템으로 전송
  • CRM 업데이트: 고객이 링크를 클릭할 때 고객 레코드 업데이트
  • Slack 알림: 중요한 링크가 클릭될 때 Slack에서 알림 받기
  • 리드 추적: 고객이 링크에 어떻게 참여하는지 추적

팁: 대부분의 자동화 사용 사례에서는 사용자 정의 웹훅보다 Make 통합 또는 Zapier 통합을 사용하는 것이 더 쉽습니다. 이들은 웹훅으로 구동되는 즉시 클릭 트리거를 포함하며 코딩이 필요하지 않습니다.

링크 수준 웹훅을 설정하는 방법

1

링크로 이동하여 구성할 링크를 클릭합니다.

2

웹훅 섹션까지 스크롤합니다.

3

웹훅 URL을 입력합니다(한 줄에 하나씩).

여러 웹훅 URL을 추가할 수 있습니다. 링크가 클릭되면 모든 URL이 동일한 페이로드를 받습니다.

웹훅 URL을 입력합니다(한 줄에 하나씩).
웹훅 URL을 입력합니다(한 줄에 하나씩).
4

저장을 클릭합니다.

링크 수준 웹훅은 해당 특정 링크가 클릭될 때만 발동합니다.

워크스페이스 수준 웹훅을 설정하는 방법

1

설정(사이드바의 기어 아이콘)으로 이동합니다.

2

워크스페이스 설정을 클릭합니다.

3

웹훅 URL을 입력합니다(한 줄에 하나씩).

여러 웹훅 URL을 추가할 수 있습니다. 워크스페이스의 모든 링크가 클릭되면 모든 URL이 동일한 페이로드를 받습니다.

웹훅 URL을 입력합니다(한 줄에 하나씩).
웹훅 URL을 입력합니다(한 줄에 하나씩).
4

설정 저장을 클릭합니다.

워크스페이스 수준 웹훅은 워크스페이스의 모든 링크에 대한 모든 클릭에서 발동합니다.

참고: 두 수준 모두에서 웹훅을 구성하면 해당 링크의 클릭에 대해 둘 다 발동합니다.

이벤트

모든 웹훅은 해당 범위에 대한 모든 이벤트 유형을 받습니다. 링크 수준 웹훅은 해당 링크에 대한 이벤트를 받고, 워크스페이스 수준 웹훅은 워크스페이스의 모든 링크에 대한 이벤트를 받습니다. 상위 수준 event 필드를 확인하여 구분합니다.

event전송 시점
click짧은 링크를 클릭합니다. 방문자의 요청 데이터가 포함된 click 객체를 포함합니다.
link.created워크스페이스에서 새 링크가 생성됩니다.
link.updated링크의 설정이 변경됩니다. 자동 저장된 편집을 포함한 모든 업데이트에서 발동하므로 편집 세션당 여러 개를 받을 수 있습니다.
link.deleted링크가 삭제됩니다. link 객체는 삭제 전에 있던 슬러그와 도메인을 유지합니다.

웹훅 페이로드

클릭 페이로드

클릭이 발생하면 Linkly는 다음 JSON 페이로드로 POST 요청을 보냅니다.

{
  "event": "click",
  "timestamp": "2025-01-15T10:30:00Z",
  "link": {
    "id": 12345,
    "name": "My Campaign Link",
    "url": "https://example.com/landing-page",
    "full_url": "https://yourdomain.com/abc123",
    "domain": "yourdomain.com",
    "slug": "/abc123",
    "metadata": {
      "order_id": "A-10293",
      "crm_contact_id": "3f2b8c1e-9a47-4d0e-b6a5-1c2d3e4f5a6b"
    },
    "destination": "https://example.com/landing-page",
    "workspace_id": 1,
    "enabled": true,
    "cloaking": false,
    "forward_params": true,
    "block_bots": true,
    "public_analytics": false,
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "spring-sale",
    "og_title": "Special Offer",
    "og_description": "Check out our spring sale!",
    "rules": [
      {
        "what": "country",
        "matches": "US",
        "url": "https://example.com/us-landing"
      }
    ]
  },
  "click": {
    "id": "01KYPGEEPJSPR3S564QRBDGA1W",
    "country": "US",
    "is_eu_country": false,
    "platform": "desktop",
    "browser_name": "Chrome",
    "referer": "https://twitter.com/",
    "isp": "Comcast",
    "bot_name": null,
    "destination": "https://example.com/landing-page",
    "params": {
      "utm_source": "twitter"
    }
  }
}

페이로드 필드

이벤트 정보

필드설명
eventclick, link.created, link.updated, 또는 link.deleted
timestamp클릭의 ISO 8601 타임스탬프

링크 객체

필드설명
id고유한 링크 식별자
name링크 별명
url원래 대상 URL
full_url짧은 링크 URL
domain사용자 정의 도메인(구성된 경우)
slugURL 경로/슬러그
metadata링크에 첨부된 자신의 키-값 데이터(예: 자신의 시스템의 ID). 항상 객체이며 설정되지 않은 경우 비어있습니다. 링크 메타데이터 참조
destination이 클릭에 대한 실제 대상(규칙이 적용된 경우 url과 다를 수 있음)
workspace_id워크스페이스 식별자
enabled링크 활성화 여부
rules리디렉션 규칙 배열(지역, 디바이스, 로테이터)
utm_*구성된 경우 UTM 매개변수
og_*구성된 경우 Open Graph 설정

클릭 객체

필드설명
id이 클릭의 고유 식별자, 26자 ULID. 선행 문자는 클릭 시간을 인코딩하므로 id는 평문 문자열로 시간순으로 정렬됩니다
country2자 국가 코드(예: "US", "GB")
is_eu_country클릭이 EU에서 시작되었는지 여부
platform디바이스 플랫폼(desktop, ios, android 등)
browser_name브라우저 이름(Chrome, Safari, Firefox 등)
referer참조 URL(사용 가능한 경우)
isp인터넷 서비스 제공자
bot_name봇 식별자(인간 클릭의 경우 null)
destination이 클릭에 대한 최종 대상 URL
params링크로 전달된 쿼리 매개변수

개인정보 보호 참고: IP 주소는 웹훅 페이로드에 포함되지 않습니다.

링크 라이프사이클 페이로드

link.created, link.updated, link.deleted 이벤트는 하나의 모양을 공유합니다. click 객체는 없습니다. event, timestamp, 그리고 전체 link을 받습니다.

{
  "event": "link.created",
  "timestamp": "2026-06-20T10:30:00Z",
  "link": {
    "id": 12345,
    "name": "My Campaign Link",
    "url": "https://example.com/landing-page",
    "full_url": "https://yourdomain.com/abc123",
    "domain": "yourdomain.com",
    "slug": "/abc123",
    "workspace_id": 1,
    "enabled": true,
    "metadata": {
      "order_id": "A-10293"
    },
    "rules": []
  }
}

자동화 플랫폼 통합

사용자 정의 코딩 없이 더 쉽게 설정하려면 네이티브 통합을 사용하세요.

  • Make 통합 - 즉시 클릭 트리거가 포함된 시각적 자동화 플랫폼
  • Zapier 통합 - 코드 없이 Linkly를 수천 개의 앱에 연결

두 통합 모두 웹훅을 사용하지만 모든 설정을 자동으로 처리합니다.

모범 사례

여러 웹훅

여러 웹훅 URL을 추가할 수 있습니다(한 줄에 하나씩). 클릭이 발생하면 모든 URL이 동일한 페이로드를 받습니다.

오류 처리

  • 웹훅은 발동-후-망각 - Linkly는 실패한 전달을 재시도하지 않습니다
  • 웹훅 실패는 리디렉션에 영향을 주지 않습니다. 사용자는 항상 목적지에 도달합니다
  • 웹훅 엔드포인트가 빠르게 응답하는지 확인하세요(5초 미만 권장)

보안

  • 웹훅 URL에 HTTPS 엔드포인트를 사용하세요
  • 웹훅 핸들러에서 들어오는 요청을 검증하세요
  • 검증을 위해 웹훅 URL에 시크릿 매개변수를 추가하는 것을 고려하세요

테스트

  1. 1
    webhook.site 또는 RequestBin과 같은 서비스를 사용하여 웹훅 URL을 설정합니다
  2. 2
    링크를 클릭합니다
  3. 3
    받은 페이로드를 검사합니다
  4. 4
    확인되면 프로덕션 웹훅 URL로 전환합니다

API 액세스

API를 통해 프로그래밍 방식으로 웹훅을 관리할 수도 있습니다.

POST   /api/v1/link/:link_id/webhooks
DELETE /api/v1/link/:link_id/webhooks/:hook_id
GET    /api/v1/link/:link_id/webhooks

POST   /api/v1/workspace/:workspace_id/webhooks
DELETE /api/v1/workspace/:workspace_id/webhooks/:hook_id
GET    /api/v1/workspace/:workspace_id/webhooks

자세한 내용은 API 설명서를 참조하세요.

웹훅 자주 묻는 질문

웹훅이 어떤 이벤트를 보낼 수 있나요?

웹훅은 페이로드의 event 필드로 식별되는 4가지 이벤트에서 발동합니다. 링크가 클릭될 때 click을 받고, 링크가 변경될 때 link.created, link.updated, link.deleted을 받습니다. 모든 웹훅은 해당 범위에 대한 모든 이벤트 유형을 받으므로 각각을 처리하기 위해 event 필드에 분기합니다.

웹훅이 발동되지 않는 이유는 무엇인가요?

웹훅 URL이 유효하고 액세스할 수 있는지 확인하고, 웹훅이 링크 또는 워크스페이스에 저장되었는지 확인하세요. 클릭 이벤트의 경우 웹훅은 클릭이 실제로 기록될 때만 발동합니다. 제외된 IP 또는 스킵된 크롤러는 이를 트리거하지 않습니다.

웹훅 페이로드의 일부 필드가 null인 이유는 무엇인가요?

정보를 사용할 수 없는 경우(예: 참조 없음), 개인정보 보호 설정이 수집을 방지했거나, 클릭이 봇에서 온 경우(이 경우 bot_name이 채워짐) 일부 필드는 null일 수 있습니다.

Linkly는 실패한 웹훅 전달을 재시도하나요?

아니요. 웹훅은 발동-후-망각입니다. 실패한 전달은 재시도되지 않으며, Linkly는 웹훅 전달 상태를 추적하지 않습니다. 웹훅 요청은 5초 후 타임아웃됩니다.

Linkly는 전환 추적을 위한 포스트백을 지원하나요?

아니요. Linkly 웹훅은 아웃바운드 전용이며 클릭이 발생할 때 발동합니다. 제휴 네트워크 또는 광고 플랫폼에서 포스트백 데이터를 받을 수 없습니다. 전환 추적의 경우 대상 플랫폼의 기본 추적을 사용하거나, 쿼리 매개변수 포워딩을 통해 클릭 ID를 전달하거나, BigQuery 통합을 사용하여 클릭 데이터를 전환 데이터와 조인합니다.

웹훅을 사용해야 할까요, 아니면 Make/Zapier를 사용해야 할까요?

대부분의 자동화 사용 사례에서는 Make 또는 Zapier 통합이 더 쉽습니다. 웹훅을 사용하지만 모든 구성을 자동으로 처리합니다. 자신의 시스템으로 데이터를 보내거나 통합에 대한 더 많은 제어가 필요할 때 사용자 정의 웹훅을 사용하세요.

링크와 워크스페이스 모두에 웹훅을 설정할 수 있나요?

예. 두 수준 모두에서 웹훅을 구성하면 해당 링크가 클릭될 때 둘 다 발동합니다. 이는 워크스페이스 전체 로깅과 특정 링크에 대한 특정 작업을 원할 때 유용합니다.

웹훅을 설정할 수 있는 사람은 누구입니까?

단일 링크의 웹훅에는 쓰기 역할 이상이 필요합니다. 작업 영역 웹훅에는 관리자 또는 소유자 역할이 필요합니다. 사용자 역할 및 권한을 참조하세요.

이용 가능 요금제

Business 이상 요금제에서 이용 가능

요금제 비교 →

월 500회 클릭 추적 무료.