メールインフラガイド
メール受信Webhookの設計パターンと安全対策
ポーリング型のメールボックス処理を作り込まずに、Webhookで受信メッセージを処理する方法を解説します。
メール受信Webhookは、メッセージが届いたときに構造化されたイベントをアプリケーションに届けます。設計上の課題は、安全なパース、認証、冪等性、そしてメッセージを失わずに再試行を処理することです。
実務での意味
- 署名付き、または認証されたWebhook配信
- 冪等な処理のためのメッセージID
- 復旧に備えた生メッセージの保持
- 添付ファイルや後続処理の非同期化
実装チェックリスト
- コンテンツをパースする前に、Webhookの送信元を検証する。
- 副作用のある処理の前に、プロバイダーのメッセージIDを永続化する。
- 時間のかかる添付ファイル処理やAI処理はキューに入れる。
- 成功レスポンスはすばやく返し、一時的な失敗時は安全に再試行する。
よく寄せられる質問
添付ファイルはWebhookリクエストの中で処理すべきですか？
通常はおすすめしません。メッセージを永続化し、添付ファイルの処理はキューに入れることで、受信確認をすばやく返せて再試行にも安全に対応できます。
重複したWebhookはどう処理すればよいですか？
プロバイダーのメッセージIDを一意のものとして扱い、後続の処理を冪等にします。