웹훅은 두 시스템 간의 메커니즘 또는 통합으로, "생산자" (FastComments)가 이벤트를 발생시키고 "소비자" (사용자)가 API 호출을 통해 해당 이벤트를 소비합니다.

FastComments는 Comment 리소스에 대해서만 웹훅을 지원합니다.

댓글 생성, 삭제 및 업데이트에 대한 웹훅을 지원합니다.

이들 각각은 시스템에서 별개의 이벤트로 간주되며, 따라서 웹훅 이벤트에 대해 서로 다른 의미 와 구조를 가집니다.

Webhooks 관리자에는 각 이벤트 유형 (Create, Update, Delete)에 대해 Send Test Payload 버튼이 있습니다. Create 및 Update 이벤트는 더미 WebhookComment 객체를 전송하며, Delete 테스트는 ID만 있는 더미 요청 본문을 전송합니다.

페이로드 검증

웹훅 통합을 테스트할 때, 들어오는 요청에 다음 헤더들이 포함되어 있는지 확인하세요:

1. token - 귀하의 API 비밀
2. X-FastComments-Timestamp - Unix 타임스탬프(초)
3. X-FastComments-Signature - HMAC-SHA256 서명

HMAC 서명 검증을 사용하여 페이로드의 진위를 확인하세요.

테스트 도구

개발 중 들어오는 웹훅 페이로드를 검사하기 위해 webhook.site 또는 ngrok과 같은 도구를 사용할 수 있습니다.

이벤트 유형

• Create Event: 새 댓글이 생성될 때 트리거됩니다. 기본 메서드: PUT
• Update Event: 댓글이 편집될 때 트리거됩니다. 기본 메서드: PUT
• Delete Event: 댓글이 삭제될 때 트리거됩니다. 기본 메서드: DELETE

각 이벤트는 요청 본문에 전체 댓글 데이터를 포함합니다 (페이로드 형식은 데이터 구조 참조).

웹후크로 전송되는 유일한 구조는 아래 TypeScript에 설명된 WebhookComment 객체입니다.

WebhookComment 객체 구조

"Create" 이벤트 구조

"create" 이벤트 요청 본문은 WebhookComment 객체입니다.

"Update" 이벤트 구조

"update" 이벤트 요청 본문은 WebhookComment 객체입니다.

"Delete" 이벤트 구조

"delete" 이벤트 요청 본문은 WebhookComment 객체입니다.

변경 — 2023년 11월 14일 기준
이전에는 "delete" 이벤트 요청 본문에 댓글 id만 포함되어 있었습니다. 이제 삭제 시점의 전체 댓글을 포함합니다.

WebhookComment 객체

Copy Run

1

2interface WebhookComment {

3 /** 댓글의 id. **/

4 id: string

5 /** 댓글 스레드를 식별하는 id 또는 URL. 정규화됨. **/

6 urlId: string

7 /** 댓글이 남겨진 위치를 가리키는 URL. **/

8 url?: string

9 /** 댓글을 남긴 사용자의 id. SSO인 경우 tenant id가 접두사로 붙습니다. **/

10 userId?: string

11 /** 댓글을 남긴 사용자의 이메일. **/

12 commenterEmail?: string

13 /** 댓글 위젯에 표시되는 사용자 이름. SSO의 경우 displayName일 수 있음. **/

14 commenterName: string

15 /** 원시 댓글 텍스트. **/

16 comment: string

17 /** 파싱 후의 댓글 텍스트. **/

18 commentHTML: string

19 /** 외부 댓글 id. **/

20 externalId?: string

21 /** 부모 댓글의 id. **/

22 parentId?: string | null

23 /** 댓글이 작성된 UTC 날짜. **/

24 date: UTC_ISO_DateString

25 /** 투표의 합산 점수 (찬성 - 반대). **/

26 votes: number

27 votesUp: number

28 votesDown: number

29 /** 사용자가 댓글 작성 당시 로그인되어 있었거나, 댓글이 인증되었거나, 세션을 인증한 경우 true. **/

30 verified: boolean

31 /** 댓글이 인증된 날짜. **/

32 verifiedDate?: number

33 /** 모더레이터가 댓글을 검토됨으로 표시했는지 여부. **/

34 reviewed: boolean

35 /** 아바타의 위치 또는 base64 인코딩. SSO로 전달된 값이 base64였던 경우에만 base64로 제공됩니다. **/

36 avatarSrc?: string

37 /** 댓글이 수동으로 또는 자동으로 스팸으로 표시되었는지 여부. **/

38 isSpam: boolean

39 /** 댓글이 자동으로 스팸으로 표시되었는지 여부. **/

40 aiDeterminedSpam: boolean

41 /** 댓글에 이미지가 있는지 여부. **/

42 hasImages: boolean

43 /** 'Most Relevant' 정렬에서 댓글이 위치한 페이지 번호. **/

44 pageNumber: number

45 /** 'Oldest First' 정렬에서 댓글이 위치한 페이지 번호. **/

46 pageNumberOF: number

47 /** 'Newest First' 정렬에서 댓글이 위치한 페이지 번호. **/

48 pageNumberNF: number

49 /** 댓글이 자동으로 승인되었는지 또는 수동으로 승인되었는지 여부. **/

50 approved: boolean

51 /** 댓글 작성 당시 사용자의 로케일 코드(형식: en_us). **/

52 locale: string

53 /** 댓글에서 성공적으로 파싱된 @멘션 목록. **/

54 mentions?: CommentUserMention[]

55 /** 댓글이 작성된 도메인. **/

56 domain?: string

57 /** 이 댓글에 연결된 선택적 모더레이션 그룹 id 목록. **/

58 moderationGroupIds?: string[]|null

59}

60

When users are tagged in a comment, the information is stored in a list called mentions. Each object in that list has the following structure.

Webhook Mentions 객체

Copy Run

1

2interface CommentUserMention {

3 /** 사용자 id. SSO 사용자의 경우 tenant id가 접두사로 붙습니다. **/

4 id: string

5 /** @ 기호를 포함한 최종 @멘션 태그 텍스트. **/

6 tag: string

7 /** @ 기호를 포함한 원본 @멘션 태그 텍스트. **/

8 rawTag: string

9 /** 태그된 사용자의 유형. user = FastComments.com 계정. sso = SSOUser. **/

10 type: 'user'|'sso'

11 /** 사용자가 알림 수신을 거부하더라도 이 값은 true로 설정됩니다. **/

12 sent: boolean

13}

14

HTTP 메서드

관리자 패널에서 각 웹후크 이벤트 유형에 대한 HTTP 메서드를 구성할 수 있습니다:

• Create Event: POST 또는 PUT (기본값: PUT)
• Update Event: POST 또는 PUT (기본값: PUT)
• Delete Event: DELETE, POST 또는 PUT (기본값: DELETE)

모든 요청에 ID가 포함되어 있으므로 Create 및 Update 작업은 기본적으로 멱등합니다 (PUT). 동일한 Create 또는 Update 요청을 반복해도 귀측에서 중복 객체가 생성되지 않아야 합니다.

요청 헤더

각 웹후크 요청에는 다음 헤더가 포함됩니다:

HMAC 서명 검증에 대한 정보는 보안 및 API 토큰에서 확인하세요.

FastComments 웹훅 요청에는 보안을 위해 여러 인증 메커니즘이 포함되어 있습니다.

전송되는 헤더

HMAC 서명 검증 (권장)

웹훅 페이로드가 진본이며 변조되지 않았는지 확인하기 위해 HMAC 서명 검증을 강력히 권장합니다.

서명 형식: sha256=<hex-encoded-signature>

서명이 계산되는 방법:

1. 결합: timestamp + "." + JSON_payload_body
2. API Secret을 키로 사용하여 HMAC-SHA256을 계산
3. 결과를 16진수로 인코딩

예시 검증 (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(req, apiSecret) {
    const timestamp = req.headers['x-fastcomments-timestamp'];
    const signature = req.headers['x-fastcomments-signature'];

    if (!timestamp || !signature) {
        return false;
    }

    // 타임스탬프가 최근인지 확인합니다 (5분 이내)
    const now = Math.floor(Date.now() / 1000);
    if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
        return false;  // 재생 공격 방지
    }

    // 서명 검증
    const payload = JSON.stringify(req.body);
    const expectedSignature = crypto
        .createHmac('sha256', apiSecret)
        .update(`${timestamp}.${payload}`)
        .digest('hex');

    return signature === `sha256=${expectedSignature}`;
}

예시 검증 (Python)

import hmac
import hashlib
import time
import json

def verify_webhook_signature(headers, body, api_secret):
    timestamp = headers.get('X-FastComments-Timestamp')
    signature = headers.get('X-FastComments-Signature')

    if not timestamp or not signature:
        return False

    # 타임스탬프가 최신인지 확인합니다
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        return False

    # 서명 검증
    payload = json.dumps(body, separators=(',', ':'))
    message = f"{timestamp}.{payload}"
    expected = hmac.new(
        api_secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    return signature == f"sha256={expected}"

예시 검증 (PHP)

function verifyWebhookSignature($headers, $body, $apiSecret) {
    $timestamp = $headers['X-FastComments-Timestamp'] ?? null;
    $signature = $headers['X-FastComments-Signature'] ?? null;

    if (!$timestamp || !$signature) {
        return false;
    }

    // 타임스탬프가 최신인지 확인합니다 (5분 이내)
    $now = time();
    if (abs($now - intval($timestamp)) > 300) {
        return false;
    }

    // 서명 검증
    $payload = json_encode($body, JSON_UNESCAPED_SLASHES);
    $message = $timestamp . '.' . $payload;
    $expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);

    return hash_equals($expectedSignature, $signature);
}

레거시 인증

하위 호환성을 위해 귀하의 API Secret이 포함된 token 헤더는 여전히 전송됩니다. 그러나 HMAC 검증은 재생 공격으로부터 보호하므로 보안 향상을 위해 HMAC 검증으로 마이그레이션할 것을 권장합니다.