Connect Webhook Guide | GroMach

개요

Webhook 통합을 통해 GroMach에서 생성된 콘텐츠 데이터를 사용자의 백엔드 시스템으로 직접 수신하고 처리할 수 있습니다. 콘텐츠를 발행하면 GroMach는 설정된 엔드포인트로 POST 요청을 통해 콘텐츠 데이터를 전송합니다.

1단계: Webhook 엔드포인트 설정

Webhook 요청을 수신할 HTTPS 엔드포인트를 서버에 생성하세요. 엔드포인트는 다음 요구사항을 충족해야 합니다:

POST 요청 처리: 모든 웹훅 데이터는 POST 방식으로 전송됩니다
HTTPS 사용: 보안을 위해 HTTPS URL만 지원됩니다
2xx 상태 코드 반환: 수신 확인을 위해 성공 상태 코드를 반환해야 합니다

2단계: 서명 검증 구현

GroMach는 HMAC-SHA256을 사용하여 모든 웹훅 요청에 서명합니다. 요청의 진위를 확인하기 위해 이 서명을 검증해야 합니다.

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

x-webhook-signature: 요청 본문의 HMAC-SHA256 서명
x-webhook-timestamp: 요청이 전송된 ISO 8601 타임스탬프
Content-Type: application/json

Node.js에서 서명 검증을 구현하는 예제입니다:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(computedSignature, 'hex')
  );
}

// In your endpoint handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, YOUR_SECRET_KEY)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the webhook...
  res.json({ success: true });
});

3단계: Webhook 페이로드 형식

콘텐츠가 발행되면 GroMach는 다음 구조의 페이로드를 전송합니다:

{
  "event_type": "publish_articles",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "articles": [
      {
        "id": "article-uuid-123",
        "slug": "my-article-slug",
        "title": "Article Title",
        "excerpt": "Brief description of the article...",
        "content_format": "markdown",
        "content": "# Full article content in markdown...",
        "status": "published",
        "published_at": "2024-01-15T10:30:00.000Z",
        "author_name": "Admin",
        "cover_image": "https://example.com/image.jpg",
        "meta_title": "SEO Title",
        "meta_description": "SEO meta description",
        "tags": ["seo", "marketing"]
      }
    ]
  }
}

콘텐츠 필드 참조

id: 콘텐츠의 고유 식별자
slug: URL 친화적인 콘텐츠 식별자
title: 콘텐츠 제목
excerpt: 간단한 설명 또는 요약
content_format: "markdown" 또는 "html"
content: 전체 콘텐츠 내용
status: 발행 상태 (draft, published, archived)
published_at: ISO 8601 형식의 발행 시간
author_name: 작성자 표시 이름
cover_image: 커버 이미지 URL (있는 경우)
meta_title: 검색 엔진용 SEO 제목
meta_description: SEO 메타 설명
tags: 태그 문자열 배열

4단계: GroMach에서 설정

GroMach 통합 페이지에서 다음 정보를 입력하세요:

이름 (선택사항): 이 웹훅을 식별할 수 있는 이름
Webhook URL: HTTPS 엔드포인트 URL (예: https://your-site.com/api/webhook)
비밀 키: 요청 서명에 사용되는 비밀 문자열 (안전하게 보관하세요!)
발행 상태: 콘텐츠를 "published" 또는 "draft" 상태로 전송할지 선택

중요

비밀 키를 안전하게 보관하고 클라이언트 측 코드에 노출하지 마세요. 서버에서 환경 변수를 사용하여 안전하게 저장하세요.

Webhook 테스트

통합을 생성하기 전에 "연결 테스트" 버튼을 사용하여 웹훅 연결을 테스트할 수 있습니다. GroMach는 엔드포인트가 올바르게 구성되었는지 확인하기 위해 테스트 요청을 전송합니다.

테스트 요구사항

테스트를 통과하려면 엔드포인트가 다음을 수행해야 합니다:

1. 서명 검증: 비밀 키를 사용하여 X-Webhook-Signature 헤더를 검증
2. 성공 응답 반환: { "success": true } JSON 응답 반환

테스트 페이로드는 다음과 같습니다:

{
  "event_type": "test",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "message": "This is a test webhook from Gromach SEO",
    "integration_name": "My Webhook"
  }
}

테스트 엔드포인트에서 요청을 처리하는 전체 예제입니다:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  // Step 1: Verify the signature
  const computedSignature = crypto
    .createHmac('sha256', YOUR_SECRET_KEY)
    .update(payload)
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(computedSignature, 'hex')
  );

  if (!isValid) {
    return res.status(401).json({
      success: false,
      error: 'Invalid signature'
    });
  }

  // Step 2: Process based on event type
  if (req.body.event_type === 'test') {
    // Test connection - just return success
    return res.json({ success: true });
  }

  if (req.body.event_type === 'publish_articles') {
    // Process articles...
    const articles = req.body.data.articles;
    // Save to your database, etc.
    return res.json({ success: true });
  }

  res.json({ success: true });
});

서명 검증이 필요한 이유

서명 검증은 웹훅 요청이 실제로 GroMach에서 전송된 것이며 변조되지 않았음을 보장합니다. 이는 엔드포인트를 무단 요청으로부터 보호하는 보안 모범 사례입니다.

문제 해결

연결 테스트 실패

• 엔드포인트 URL이 올바르고 HTTPS를 사용하는지 확인하세요
• 서버가 인터넷에서 접근 가능한지 확인하세요
• 엔드포인트가 2xx 상태 코드를 반환하는지 확인하세요

서명 검증 실패

• GroMach의 정확한 비밀 키를 사용하고 있는지 확인하세요
• 파싱된 객체가 아닌 원시 요청 본문을 해싱하고 있는지 확인하세요
• 타이밍 공격을 방지하기 위해 타이밍 세이프 비교를 사용하세요

콘텐츠가 표시되지 않음

• 서버 로그에서 처리 오류가 있는지 확인하세요
• 콘텐츠 상태가 예상 워크플로와 일치하는지 확인하세요
• 데이터베이스 작업이 성공적으로 완료되고 있는지 확인하세요

Webhook 통합 가이드

개요