FastComments를 사용하면 댓글이 시스템에 추가되거나, 업데이트되거나, 제거될 때마다 API 엔드포인트를 호출할 수 있습니다.
우리는 이를 HTTP/HTTPS를 통한 비동기 웹후크로 구현합니다.
웹후크란 무엇인가 
웹훅은 두 시스템 간의 메커니즘 또는 통합으로, "생산자" (FastComments)가 이벤트를 발생시키고 "소비자" (사용자)가 API 호출을 통해 해당 이벤트를 소비합니다.
지원되는 이벤트 및 리소스
FastComments는 Comment 리소스에 대해서만 웹훅을 지원합니다.
댓글 생성, 삭제 및 업데이트에 대한 웹훅을 지원합니다.
이들 각각은 시스템에서 별개의 이벤트로 간주되며, 따라서 웹훅 이벤트에 대해 서로 다른 의미 와 구조를 가집니다.
로컬 개발 설정
로컬 개발의 경우 ngrok와 같은 도구를 사용하세요.
시스템 보안을 단순화하기 위해 로컬 개발은 다른 환경을 설정하고 보안을 유지하는 것과 동일한 절차를 따릅니다.
Step 1: Add "localhost" to domains in your account.
"localhost"를 여기에 도메인으로 추가하세요.
Step 2: Pick an API Key
도메인에 대한 웹훅 구성을 추가할 예정이므로 API 키가 필요합니다. 여기에서 할 수 있습니다.
Under "Associate with domain" - select your "localhost" domain.
NOTE: Alternatively, you can use one API Secret for all testing activity and staging environments. Simply add an API Secret for "All Domains", and give it a name like "test".
운영 도메인에 대해 API Secret이 정의되어 있는지 확인하세요. 다른 모든 도메인의 이벤트는 와일드카드(테스트) 시크릿을 사용합니다.
Step 3: Add Your Webhook
ngrok 또는 유사한 도구를 실행하는 동안 "localhost"의 값을 여기에서 설정하세요.
When clicking Send Test Payload, we will send two test events to check that you validate the API key.
Once it validates, hit Save.
Step 4: Add A Comment
이제 댓글을 추가, 편집 또는 삭제할 수 있으며 테스트용 API 키를 사용하여 이벤트가 로컬 개발 머신으로 전달되는 것을 볼 수 있어야 합니다. 최대 30초의 지연 이벤트가 머신에 도달하는 데 있을 수 있습니다.
설정
localhost에 대해서도 프로덕션에서 한 것과 동일한 단계를 따르세요. 프로덕션 도메인과 API Secrets가 설정되어 있는지 확인하세요.
먼저 웹후크 관리자로 이동하세요. 이는 데이터 관리 -> 웹후크에서 접근할 수 있습니다.
구성 페이지는 다음과 같이 표시됩니다:
이 페이지에서 각 댓글 이벤트 유형에 대한 엔드포인트를 지정할 수 있습니다.
각 이벤트 유형마다 통합이 올바르게 설정되었는지 확인하려면 반드시 'Send Test Payload'를 클릭하세요. 자세한 내용은 다음 섹션 "테스트"를 참조하세요.
테스트
Webhooks admin에는 각 이벤트 유형(Create, Update, Delete)마다 Send Test Payload 버튼이 있습니다. Create 및 Update 이벤트는 더미 WebhookComment 객체를 전송하고, Delete 테스트는 ID만 포함된 더미 요청 본문을 전송합니다.
페이로드 검증
웹훅 통합을 테스트할 때 들어오는 요청에 다음 헤더들이 포함되어 있는지 확인하세요:
token- 귀하의 API 비밀X-FastComments-Timestamp- Unix 타임스탬프(초)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만 포함되어 있었습니다. 이제는 삭제 시점의 전체 댓글이 포함됩니다.
Run 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.
Run HTTP 메서드
관리자 패널에서 각 웹훅 이벤트 유형에 대한 HTTP 메서드를 구성할 수 있습니다:
- Create 이벤트: POST 또는 PUT (기본값: PUT)
- Update 이벤트: POST 또는 PUT (기본값: PUT)
- Delete 이벤트: DELETE, POST 또는 PUT (기본값: DELETE)
모든 요청에 ID가 포함되어 있으므로 Create 및 Update 작업은 기본적으로 멱등성(PUT)을 가집니다. 동일한 Create 또는 Update 요청을 반복해도 귀측에서 중복 객체가 생성되지 않아야 합니다.
요청 헤더
각 웹훅 요청에는 다음 헤더들이 포함됩니다:
| Header | 설명 |
|---|---|
Content-Type | application/json |
token | 귀하의 API 시크릿 |
X-FastComments-Timestamp | 요청이 서명된 시점의 Unix 타임스탬프(초) |
X-FastComments-Signature | HMAC-SHA256 서명 (sha256=<hex>) |
See Security & API Tokens for information on verifying the HMAC signature.
보안 및 API 토큰
FastComments 웹훅 요청에는 보안을 위해 여러 인증 메커니즘이 포함되어 있습니다.
전송되는 헤더
| 헤더 | 설명 |
|---|---|
token | 귀하의 API Secret(하위 호환성용) |
X-FastComments-Timestamp | 요청이 서명될 때의 Unix 타임스탬프(초) |
X-FastComments-Signature | 페이로드의 HMAC-SHA256 서명 |
HMAC 서명 검증 (권장)
웹훅 페이로드가 진본이며 변조되지 않았는지 확인하기 위해 HMAC 서명 검증을 강력히 권장합니다.
서명 형식: sha256=<hex-encoded-signature>
서명이 계산되는 방법:
- 결합:
timestamp + "." + JSON_payload_body - API Secret을 키로 사용하여 HMAC-SHA256을 계산
- 결과를 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 검증으로 마이그레이션할 것을 권장합니다.
동작 방식 및 재시도 처리
시스템 내 Comment 객체에 대한 모든 변경은 이벤트를 발생시키며 그 이벤트는 큐에 들어갑니다.
초기 웹훅 이벤트는 보통 이벤트 소스가 발생한 후 6초 이내에 전송됩니다.
API가 다운되는 경우를 대비해 Webhooks 관리자에서 이 큐를 모니터링할 수 있습니다.
귀하의 API에 대한 요청이 실패하면, 우리는 그것을 일정에 따라 다시 큐에 넣습니다.
That schedule is 1 Minute * the retry count. If the call fails once, it'll try again in
a minute. If it fails twice, it'll then wait two minutes, and so on. This is so that we
don't overload your API if you are going down to load related reasons.
웹훅은 로그 페이지에서 취소할 수 있습니다.
결론
이로써 우리의 Webhooks 문서가 마무리됩니다.
FastComments Webhook 통합이 이해하기 쉽고 빠르게 설정되기를 바랍니다.
문서에서 누락된 부분을 발견하셨다고 생각되면 아래에 알려주세요.