webhook-integration

Webhook 連携

目次

• 概要
• 使用する場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

イベント駆動型アーキテクチャ向けに堅牢な Webhook システムを実装し、サービス間およびサードパーティ連携とのリアルタイム通信を可能にします。

使用する場面

• サードパーティサービスとの連携（Stripe、GitHub、Shopify）
• イベント通知システム
• リアルタイムデータ同期
• 自動ワークフローのトリガー
• 決済処理のコールバック
• CI/CD パイプラインの通知
• ユーザーアクティビティの追跡
• マイクロサービス間の通信

クイックスタート

最小限の動作例：

import crypto from "crypto";
import axios from "axios";

interface WebhookEvent {
  id: string;
  type: string;
  timestamp: number;
  data: any;
}

interface WebhookEndpoint {
  url: string;
  secret: string;
  events: string[];
  active: boolean;
}

interface DeliveryAttempt {
  attemptNumber: number;
  timestamp: number;
  statusCode?: number;
  error?: string;
  duration: number;
}

// ... (see reference guides for full implementation)

リファレンスガイド

references/ ディレクトリにある詳細な実装：

ガイド	内容
Webhook 送信側（TypeScript）	Webhook 送信側（TypeScript）
Webhook 受信側（Express）	Webhook 受信側（Express）
Bull を使った Webhook キュー	Bull を使った Webhook キュー
Webhook テストユーティリティ	Webhook テストユーティリティ

ベストプラクティス

✅ 推奨事項

• 検証には HMAC 署名を使用する
• イベント ID で冪等性を実装する
• すぐに 200 OK を返し、非同期で処理する
• リトライには指数バックオフを実装する
• リプレイ攻撃を防ぐためにタイムスタンプを含める
• 確実な配信にはキューシステムを使用する
• すべての配信試行を記録する
• Webhook テストツールを提供する
• Webhook ペイロードのスキーマを文書化する
• Webhook 管理 UI を実装する
• イベントタイプによるフィルタリングを可能にする
• Webhook のバージョン管理に対応する

❌ 禁止事項

• Webhook で機密データを送信する
• 署名検証を省略する
• 時間のかかる処理で応答をブロックする
• 無期限にリトライする
• 内部エラーの詳細を公開する
• （本番環境で）Webhook を localhost に送信する
• タイムアウト処理を忘れる
• レート制限を省略する