웹훅

웹훅을 통해 링크에 대한 실시간 알림을 받을 수 있습니다. 링크가 클릭될 때와 생성, 업데이트 또는 삭제될 때 모두 가능합니다. Linkly는 각 이벤트에 대한 상세 정보와 함께 지정된 URL로 POST 요청을 전송합니다.

사용 사례

• 자동화 플랫폼: Make 또는 Zapier에서 링크가 클릭될 때 워크플로우 트리거
• 사용자 정의 분석: 클릭 데이터를 자신의 분석 시스템으로 전송
• CRM 업데이트: 고객이 링크를 클릭할 때 고객 기록 업데이트
• Slack 알림: 중요한 링크가 클릭될 때 Slack에서 알림 받기
• 리드 추적: 영업 담당자가 링크와 상호작용할 때 추적

팁: 대부분의 자동화 사용 사례의 경우, 사용자 정의 웹훅보다 Make 통합 또는 Zapier 통합을 설정하는 것이 더 쉽습니다. 이들은 코딩이 필요 없는 웹훅을 기반으로 한 즉시 클릭 트리거를 포함합니다.

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

이벤트

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

웹훅 페이로드

클릭 페이로드

클릭이 발생하면 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",
    "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"
    }
  }
}

페이로드 필드

이벤트 정보

링크 객체

클릭 객체

개인정보 보호 참고: 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,
    "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 문서를 참고하세요.