웹훅 설정 가이드

웹훅이란?

웹훅은 모니터링 중인 콘텐츠가 설정한 임계값을 충족할 때 SNSTracker가 자동으로 서버나 애플리케이션으로 알림을 보내는 기능입니다. 예를 들어 영상의 조회수가 크게 증가하거나 채널에 새 팔로워가 늘어나면 SNSTracker가 웹훅 URL로 알림을 전송합니다(일반적으로 1분 이내).

단계별 설정 가이드

1단계: 웹훅 엔드포인트 준비

SNSTracker에서 설정하기 전에 웹훅 엔드포인트를 준비해야 합니다. 이는 HTTP POST 요청을 받을 수 있는 URL입니다.

웹훅 엔드포인트 옵션:

자체 서버: https://api.yourcompany.com/webhook
클라우드 함수: AWS Lambda, Google Cloud Functions, Azure Functions 등
자동화 플랫폼: Zapier, Make.com, n8n 등
테스트 서비스: webhook.site (테스트용)

요구 사항:

HTTPS 사용 필수(URL이 https://로 시작)
POST 요청을 수신해야 함
성공 시 HTTP 200-299 상태 코드를 반환해야 함

2단계: SNSTracker에 웹훅 타깃 추가

Collections 페이지로 이동
- SNSTracker에 로그인
- 왼쪽 사이드바(Track 섹션)에서 Collections 클릭
- 또는 바로 이동: /dashboard/collections
알림 대상 관리 열기
- Collections 페이지에서 "Manage Notify Targets" 버튼 클릭
- 알림 대상 관리 다이얼로그가 열림
새 타깃 추가
- "Add Target" 버튼 클릭
- 새 알림 타깃 생성 다이얼로그가 표시됨
Webhook 타입 선택
- 다이얼로그의 "Type" 드롭다운에서
- "Webhook" 선택
Webhook URL 입력
- "Webhook URL" 필드에 웹훅 엔드포인트 URL 입력
- 예시: https://api.yourcompany.com/webhook
- 중요: URL은 반드시 https://로 시작해야 함
코멘트 추가(선택)
- "Comment" 필드에 이 웹훅의 용도를 기억하기 위한 메모 입력 가능
- 예: "TikTok 모니터링용 운영 웹훅"
- 최대 50자
서명 키 설정(선택, 운영 환경 권장)
- "Extra" 필드에 서명 키를 포함한 JSON 객체를 추가할 수 있음:
```
{
  "signature_key": "your-secret-key-here"
}
```
- 이 키는 요청이 정품인지 검증하는 데 사용됨
- 제공하지 않으면 SNSTracker가 API 키 또는 웹훅 URL을 서명 키로 사용함
웹훅 타깃 저장
- "Save" 버튼 클릭
- 웹훅 타깃이 생성되어 사용할 준비가 완료됨

3단계: 컬렉션에서 알림 규칙 설정

컬렉션 설정 열기
- Collections 페이지로 돌아가기
- 알림을 설정할 컬렉션 찾기
- Edit 버튼 클릭(또는 컬렉션 이름 클릭하여 설정 열기)
Feed Notify 활성화(영상/게시물용)
- 컬렉션 설정에서 "Feed Notify" 섹션 찾기
- "Enable Notifications" 스위치를 ON으로 전환
- "Notify Targets" 드롭다운에서 웹훅 타깃 선택
- 모니터링할 "Metrics" 선택:
  - 조회수
  - 참여도(좋아요 + 댓글 + 공유)
- "Threshold" 값 설정:
  - 지정한 수치만큼 증가 시 알림(예: 1000)
  - 0으로 설정하면 매번 성공적으로 새로고침 후 알림
- "Save" 또는 "Update" 클릭
Channel Notify 활성화(계정용)
- 동일한 컬렉션 설정에서 "Channel Notify" 섹션 찾기
- "Enable Notifications" 스위치를 ON으로 전환
- "Notify Targets" 드롭다운에서 웹훅 타깃 선택
- 모니터링할 "Metrics" 선택:
  - 팔로워
  - 팔로잉
  - 좋아요
- "Threshold" 값 설정:
  - 지정한 수치만큼 증가 시 알림(예: 500)
  - 0으로 설정하면 매번 성공적으로 새로고침 후 알림
- "Save" 또는 "Update" 클릭
설정 확인
- 웹훅 타깃과 알림 규칙이 모두 저장되었는지 확인
- 이제 설정한 임계값이 충족되면 웹훅으로 알림이 전송됨

4단계: 웹훅 테스트

테스트 서비스 사용(처음 설정 시 권장)
- webhook.site 방문
- 제공되는 고유 URL 복사(예: https://webhook.site/unique-id)
- 2단계의 웹훅 URL로 이 URL 사용
- 임계값 0으로 알림 설정(변경 사항 발생 시 트리거)
- SNSTracker가 콘텐츠를 확인할 때까지 대기
- webhook.site에서 알림 수신 여부 확인
엔드포인트 로그 확인
- 자체 서버 사용 시 서버 로그 확인
- SNSTracker의 POST 요청 수신 여부 확인
- 요청 본문에 예상 데이터가 포함되어 있는지 검증
알림 포맷 확인
- 알림은 다음을 포함한 JSON 객체여야 함:
  - title: 알림 설명
  - type: "feed" 또는 "channel"
  - timestamp: 알림 전송 시각
  - data: 알림을 트리거한 항목 배열

웹훅 알림 전송 방식

SNSTracker는 웹훅 전송을 최적화하기 위해 배치 메커니즘을 사용합니다:

즉시 감지: 모니터링 중인 리소스(피드 또는 채널)가 성공적으로 새로고침되고 임계값을 충족하면 즉시 알림 대상으로 표시됩니다.
1분 배치 윈도우: 개별 알림을 즉시 보내지 않고, 1분 동안의 모든 대상 알림을 모읍니다.
통합 전송: 1분이 끝나면 해당 기간의 모든 알림을 하나의 웹훅 요청으로 병합해 전송합니다.

예시 시나리오:

10:00:15에 피드 A가 임계값 충족 → 표시됨
10:00:45에 피드 B가 임계값 충족 → 표시됨
10:01:00에 피드 A와 피드 B가 하나의 웹훅 요청으로 전송됨

장점:

엔드포인트로의 HTTP 요청 수를 줄임
효율을 높이고 서버 부하를 감소
빠른 데이터 변화 시 알림 스팸 방지
배치 기간 내 모든 알림이 data 배열에 포함됨

참고: 리소스가 임계값을 충족한 시점부터 웹훅 전송까지의 최대 지연은 1분입니다. 이는 시스템 효율을 유지하면서도 거의 실시간 알림을 보장합니다.

어떤 데이터를 받게 되나요?

알림이 트리거되면 다음과 같은 JSON 데이터를 포함한 POST 요청을 받습니다:

{
  "title": "SNSTracker Notification: Feed Views Increased",
  "type": "feed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": [
    {
      "feed_id": "feed-123",
      "url": "https://www.tiktok.com/@user/video/123",
      "platform_name": "TikTok",
      "view_count": 10000,
      "like_count": 2000,
      "changed_views": 1000,
      "changed_engagement": 50
    }
  ]
}

Feed 알림 데이터 필드

feed_id: 고유 식별자
url: 영상/게시물 직접 링크
platform_name: 플랫폼(TikTok, Instagram 등)
title: 콘텐츠 제목
description: 콘텐츠 설명
author_username: 작성자 사용자명
author_nickname: 작성자 표시 이름
view_count: 총 조회수
like_count: 총 좋아요 수
comment_count: 총 댓글 수
share_count: 총 공유 수
changed_views: 지난 확인 이후 증가한 조회수
changed_engagement: 증가한 참여도(좋아요 + 댓글 + 공유)

Channel 알림 데이터 필드

id: 채널 고유 식별자
channel_url: 채널/프로필 직접 링크
platform_name: 플랫폼 이름
nickname: 표시 이름
username: 사용자명/핸들
followers: 총 팔로워 수
followings: 총 팔로잉 수
likes: 총 좋아요 수
changed_followers: 지난 확인 이후 증가한 팔로워
changed_followings: 지난 확인 이후 증가한 팔로잉
changed_likes: 지난 확인 이후 증가한 좋아요

보안: 서명 검증

SNSTracker는 요청의 진위 여부를 확인하기 위해 X-Signature 헤더에 서명을 포함합니다. 서명 키는 다음 순서로 결정됩니다:

Extra 필드의 signature_key(제공된 경우)
첫 번째 활성 API 키(signature_key가 없을 때)
웹훅 URL(대체값)

운영 환경에서는 요청이 정품인지 확인하기 위해 서명 검증을 권장합니다.

문제 해결

웹훅이 알림을 받지 못하는 경우

웹훅 URL 확인
- URL이 올바르고 접근 가능한지 확인
- https://로 시작하는지 확인
- POST 요청으로 수동 테스트
알림 설정 확인
- 컬렉션에서 알림이 활성화되어 있는지 확인
- 웹훅 타깃이 선택되어 있는지 확인
- 임계값이 올바르게 설정되어 있는지 확인
엔드포인트 상태 확인
- 엔드포인트가 실행 중이고 접근 가능한지 확인
- 서버 로그에서 들어오는 요청 확인
- 엔드포인트가 성공 상태 코드(200-299)를 반환하는지 확인

일반적인 문제

문제: "Webhook URL already exists"
해결: 웹훅 URL은 팀당 한 번만 사용할 수 있습니다. 다른 URL을 사용하거나 기존 타깃을 수정하세요.

문제: 알림이 트리거되지 않음
해결:

임계값을 0으로 설정해 테스트(변경 시마다 알림)
SNSTracker가 콘텐츠를 확인할 때까지 대기(정기적으로 확인함)
콘텐츠가 실제로 임계값만큼 변경되었는지 확인

문제: 타임아웃 오류
해결: 엔드포인트는 30초 이내에 응답해야 합니다. 엔드포인트 응답 시간을 최적화하세요.

도움이 필요하신가요?

문제가 발생하면:

웹훅 URL 접근 가능 여부 확인
알림 설정이 활성화되어 있는지 확인
임계값이 올바르게 설정되어 있는지 확인
문제가 계속되면 지원팀에 문의

즐거운 트래킹 되세요! 🚀

웹훅 설정 가이드

On this page