Webhook ドキュメント

概要

Webhook を使えば、コンテンツプラットフォームに関連する HTTP リクエストを受信できます。特定のイベント（新しい投稿の作成や公開など）が発生すると、設定したエンドポイントにイベントの詳細を含む POST リクエストが送信されます。

利用可能なイベント

現在リッスンできる WEBHOOK_EVENTS イベントがあります。以下に各イベントの詳細とデータペイロードの例を示します。

export const WEBHOOK_EVENTS = {
  // 投稿イベント
  POST_CREATED: "post.created",
  POST_PUBLISHED: "post.published",
  POST_DELETED: "post.deleted",
 
  // サイトイベント
  SITE_CREATED: "site.created",
 
  // サブスクリプションイベント
  SUBSCRIPTION_CREATED: "subscription.created",
  SUBSCRIPTION_CANCELLED: "subscription.cancelled",
 
  TEST: "test.event",
} as const

署名の検証

セキュリティを確保するため、Webhook リクエストが本当にプラットフォームからのものかどうかを常に検証してください。各リクエストには検証用の署名が含まれています。

署名ヘッダー

署名は X-Webhook-Signature ヘッダーで送信されます。署名は、Webhook のシークレットキーを使って生のリクエストボディから作成された HMAC-SHA256 ハッシュです。

X-Webhook-Signature: a1b2c3d4e5f6...

検証プロセス

1. ダッシュボードから Webhook のシークレットキーを取得。
2. シークレットキーを使って生のリクエストボディの HMAC-SHA256 ハッシュを計算。
3. 計算したハッシュを X-Webhook-Signature ヘッダーの署名と比較。
4. タイミング攻撃を防ぐためにタイミングセーフな比較関数を使用。

実装例

異なるプログラミング言語での Webhook の処理と検証のコード例を紹介します。

const crypto = require('crypto');
const express = require('express');
const app = express();
 
app.use(express.json());
 
// ダッシュボードからの Webhook シークレット
const WEBHOOK_SECRET = 'your_webhook_secret_here';
 
function verifySignature(payload, signature) {
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}
 
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifySignature(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }
  
  const { event } = req.body;
  
  switch (event.type) {
    case 'post.created':
      console.log('New post created:', event.data.title);
      break;
    // ... 他のイベントを処理
    default:
      console.log('Unhandled event:', event.type);
  }
  
  res.status(200).send('OK');
});
 
app.listen(3000, () => {
  console.log('Webhook server running on port 3000');
});

ペイロードの構造

すべての Webhook ペイロードは標準的な JSON 構造に従います。

標準ペイロード

ルートオブジェクトには、配信に関する詳細、イベントそのもの、トリガーした Webhook の情報が含まれます。

{
  "id": "delivery-uuid",
  "event": {
    "type": "post.created",
    "data": {
      "id": "post_123",
      "title": "My New Post",
      "...": "イベント固有のデータ"
    },
    "timestamp": "2024-01-15T10:30:00Z",
    "site_id": "site_789",
    "user_id": "user_456"
  },
  "webhook": {
    "id": "webhook_abc",
    "name": "My Webhook"
  }
}

ヘッダー

各 Webhook リクエストには以下の標準 HTTP ヘッダーが含まれます：

• Content-Type: application/json
• X-Webhook-Signature: [signature]
• X-Webhook-Event: [event.type]
• X-Webhook-Delivery: [delivery.id]
• User-Agent: Position-Webhooks/1.0

ベストプラクティス

Webhook 連携をセキュア、信頼性高く、高パフォーマンスにするためのベストプラクティスです。

セキュリティ

• 常に Webhook 署名を検証。リクエストが信頼できるソースからのものであることを確認するために不可欠です。
• HTTPS エンドポイントを使用して、転送中のデータを保護。
• Webhook シークレットを安全に保管し、定期的なローテーションを検討。

信頼性

• エンドポイントは正常受信を確認するために HTTP 200 ステータスコードで応答する必要があります。他のステータスコードは失敗とみなされます。
• エンドポイントを冪等（べきとう）に設計。X-Webhook-Delivery ID を使って重複イベントを検出・処理。
• 時間のかかるタスクにはキューイングシステムを使用。Webhook を即座に確認（200 レスポンス）し、バックグラウンドでタスクを処理。

パフォーマンス

Webhook リクエストにはできるだけ迅速に応答してください。理想的には数秒以内です。30 秒後にタイムアウトします。 エンドポイントのパフォーマンスと稼働時間を監視し、サービスに影響が出る前に問題をキャッチしましょう。