웹훅
웹훅을 사용하면 링크가 클릭될 때와 생성, 업데이트, 삭제될 때를 포함하여 링크에 대한 실시간 알림을 받을 수 있습니다. Linkly는 각 이벤트에 대한 자세한 정보를 포함하여 지정된 URL에 POST 요청을 보냅니다.
사용 사례
- 자동화 플랫폼: 링크가 클릭될 때 Make 또는 Zapier에서 워크플로우 트리거
- 사용자 정의 분석: 클릭 데이터를 자신의 분석 시스템으로 전송
- CRM 업데이트: 고객이 링크를 클릭할 때 고객 레코드 업데이트
- Slack 알림: 중요한 링크가 클릭될 때 Slack에서 알림 받기
- 리드 추적: 고객이 링크에 어떻게 참여하는지 추적
팁: 대부분의 자동화 사용 사례에서는 사용자 정의 웹훅보다 Make 통합 또는 Zapier 통합을 사용하는 것이 더 쉽습니다. 이들은 웹훅으로 구동되는 즉시 클릭 트리거를 포함하며 코딩이 필요하지 않습니다.
참고: 두 수준 모두에서 웹훅을 구성하면 해당 링크의 클릭에 대해 둘 다 발동합니다.
이벤트
모든 웹훅은 해당 범위에 대한 모든 이벤트 유형을 받습니다. 링크 수준 웹훅은 해당 링크에 대한 이벤트를 받고, 워크스페이스 수준 웹훅은 워크스페이스의 모든 링크에 대한 이벤트를 받습니다. 상위 수준 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"
}
}
}
페이로드 필드
이벤트 정보
| 필드 | 설명 |
|---|---|
event | click, link.created, link.updated, 또는 link.deleted |
timestamp | 클릭의 ISO 8601 타임스탬프 |
링크 객체
| 필드 | 설명 |
|---|---|
id | 고유한 링크 식별자 |
name | 링크 별명 |
url | 원래 대상 URL |
full_url | 짧은 링크 URL |
domain | 사용자 정의 도메인(구성된 경우) |
slug | URL 경로/슬러그 |
metadata | 링크에 첨부된 자신의 키-값 데이터(예: 자신의 시스템의 ID). 항상 객체이며 설정되지 않은 경우 비어있습니다. 링크 메타데이터 참조 |
destination | 이 클릭에 대한 실제 대상(규칙이 적용된 경우 url과 다를 수 있음) |
workspace_id | 워크스페이스 식별자 |
enabled | 링크 활성화 여부 |
rules | 리디렉션 규칙 배열(지역, 디바이스, 로테이터) |
utm_* | 구성된 경우 UTM 매개변수 |
og_* | 구성된 경우 Open Graph 설정 |
클릭 객체
| 필드 | 설명 |
|---|---|
id | 이 클릭의 고유 식별자, 26자 ULID. 선행 문자는 클릭 시간을 인코딩하므로 id는 평문 문자열로 시간순으로 정렬됩니다 |
country | 2자 국가 코드(예: "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": []
}
}
자동화 플랫폼 통합
사용자 정의 코딩 없이 더 쉽게 설정하려면 네이티브 통합을 사용하세요.
두 통합 모두 웹훅을 사용하지만 모든 설정을 자동으로 처리합니다.
모범 사례
여러 웹훅
여러 웹훅 URL을 추가할 수 있습니다(한 줄에 하나씩). 클릭이 발생하면 모든 URL이 동일한 페이로드를 받습니다.
오류 처리
- 웹훅은 발동-후-망각 - Linkly는 실패한 전달을 재시도하지 않습니다
- 웹훅 실패는 리디렉션에 영향을 주지 않습니다. 사용자는 항상 목적지에 도달합니다
- 웹훅 엔드포인트가 빠르게 응답하는지 확인하세요(5초 미만 권장)
보안
- 웹훅 URL에 HTTPS 엔드포인트를 사용하세요
- 웹훅 핸들러에서 들어오는 요청을 검증하세요
- 검증을 위해 웹훅 URL에 시크릿 매개변수를 추가하는 것을 고려하세요
테스트
- 1webhook.site 또는 RequestBin과 같은 서비스를 사용하여 웹훅 URL을 설정합니다
- 2링크를 클릭합니다
- 3받은 페이로드를 검사합니다
- 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 통합이 더 쉽습니다. 웹훅을 사용하지만 모든 구성을 자동으로 처리합니다. 자신의 시스템으로 데이터를 보내거나 통합에 대한 더 많은 제어가 필요할 때 사용자 정의 웹훅을 사용하세요.
링크와 워크스페이스 모두에 웹훅을 설정할 수 있나요?
예. 두 수준 모두에서 웹훅을 구성하면 해당 링크가 클릭될 때 둘 다 발동합니다. 이는 워크스페이스 전체 로깅과 특정 링크에 대한 특정 작업을 원할 때 유용합니다.
웹훅을 설정할 수 있는 사람은 누구입니까?
단일 링크의 웹훅에는 쓰기 역할 이상이 필요합니다. 작업 영역 웹훅에는 관리자 또는 소유자 역할이 필요합니다. 사용자 역할 및 권한을 참조하세요.
월 500회 클릭 추적 무료.

