webhook で受信メールを受け取る

受信トレイのポーリングでも動きますが、遅延が増え、リクエストを無駄にします。webhook はモデルを反転させます。ループの中で「メールはまだ？」と尋ねる代わりに、メッセージが着地した瞬間にサービスがあなたを呼び出すのです。このガイドでは、受信メール webhook が MoeMail の API でどう動くか、そして信頼性高く扱う方法を取り上げます。

ポーリング vs webhook

ポーリングは、何か現れるまでメッセージのエンドポイントを繰り返し叩きます。単純ですが、遅く、クォータを食います。webhook は、イベント（ここでは新着の受信メール）が起きたときに事業者が POST してくる、あなた所有の URL です。あなたのエンドポイントはループなしで即座に反応します。

仕組み

あなたが管理する webhook URL を登録する（バックエンドのルート、またはテストハーネスが公開するエンドポイント）。
あなたの一時メールボックスにメールが届くと、MoeMail がその URL にメッセージのペイロードを POST する。
ハンドラーがリクエストを検証し、メールを解析して動作する。保存する、待機中のテストステップを解決する、あるいは下流の処理を起動する。

速く応答する — さもないとリトライされる

webhook ハンドラーは素早く（数秒以内に）2xx ステータスで応答しなければなりません。2xx 以外、あるいは遅いハンドラーは失敗とみなされリトライされます。そのため、もたついたハンドラーは同じイベントを何度も受け取りかねません。ここから二つの原則が導かれます。ハンドラーは軽量に保つこと（重い DB 処理をインラインで行わず、キューに入れる）、そして処理をべき等にして重複配信が無害になるようにすることです。

ペイロードを検証する

webhook URL は事実上公開されているので、信頼する前に、そのリクエストが本当に MoeMail から来たものか確認してください。アカウントで設定した署名や共有シークレットを検証し、想定外の形は無視し、検証していない入力で決して動作しないことです。

テストでの webhook

メール認証テストの自動化では、webhook がポーリングを完全になくします。テストは webhook 発火時に解決される Promise を待ち、リンクやコードを抽出します。ポーリングループよりずっと速く、はるかに不安定になりにくい方法です。

はじめましょう

webhook ペイロードの形式は OpenAPI ドキュメントを、URL をハンドラーに向け、メールボックスを作成して自分にテストメッセージを送ってみてください。