Connect Webhook Guide | GroMach

概要

Webhook連携を使用すると、GroMachから記事データを受信し、独自のバックエンドシステムで処理できます。記事を公開すると、GroMachは設定されたエンドポイントに記事コンテンツを含むPOSTリクエストを送信します。

ステップ1: Webhookエンドポイントの設定

Webhookリクエストを受信するために、サーバーにHTTPSエンドポイントを作成します。エンドポイントは以下の要件を満たす必要があります:

POSTリクエストを受け入れる: すべてのWebhookデータはPOSTで送信されます
HTTPSを使用する: セキュリティのため、HTTPS URLのみがサポートされます
2xxステータスを返す: 受信確認として成功ステータスコードを返します

ステップ2: 署名検証の実装

GroMachはすべてのWebhookリクエストに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を識別するための名前
Webhook URL: HTTPSエンドポイントのURL（例: https://your-site.com/api/webhook）
シークレットキー: リクエストの署名に使用される秘密文字列（安全に保管してください！）
公開ステータス: 記事を "published" または "draft" として送信するかを選択

重要

シークレットキーは安全に保管し、クライアント側のコードに公開しないでください。環境変数を使用してサーバー上に安全に保存してください。

Webhookのテスト

連携を作成する前に、「接続テスト」ボタンを使用して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 });
});

署名検証が必要な理由

署名検証により、Webhookリクエストが確実にGroMachからのものであり、改ざんされていないことを確認できます。これは、エンドポイントを不正なリクエストから保護するセキュリティのベストプラクティスです。

トラブルシューティング

接続テストが失敗する

• エンドポイントURLが正しく、HTTPSを使用していることを確認してください
• サーバーがインターネットからアクセス可能であることを確認してください
• エンドポイントが2xxステータスコードを返していることを確認してください

署名検証が失敗する

• GroMachで設定したシークレットキーと完全に同じものを使用していることを確認してください
• パースされたオブジェクトではなく、生のリクエストボディをハッシュ化していることを確認してください
• タイミング攻撃を防ぐために、タイミングセーフな比較を使用してください

記事が表示されない

• サーバーログで処理エラーがないか確認してください
• 記事のステータスが期待されるワークフローと一致していることを確認してください
• データベース操作が正常に完了していることを確認してください

Webhook統合ガイド

概要