Webhook Integration

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

Overview

イベント駆動型アーキテクチャ用の堅牢な webhook システムを実装し、サービス間および第三者統合を間でのリアルタイム通信を実現します。

When to Use

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

Quick Start

最小限の動作例:

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)

Reference Guides

references/ ディレクトリの詳細な実装:

Best Practices

✅ DO

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

❌ DON'T

• webhook で機密データを送信しない
• 署名検証をスキップしない
• 重い処理でレスポンスをブロックしない
• 無期限にリトライしない
• 内部エラーの詳細を公開しない
• localhost への webhook 送信をしない (本番環境で)
• タイムアウト処理を忘れない
• レート制限をスキップしない