Webhook

イベントをリアルタイムで受け取り、各メッセージがどうなったかをシステムが常に把握できます。すべてのリクエストを署名で検証してください。

webhookの仕組み

ダッシュボードでHTTPSエンドポイントを登録し、受け取るイベントを選択します。メッセージに何かが起きると、MigoSMTPがJSON本文付きのPOSTリクエストをエンドポイントに送信します。

イベントタイプ

システムに必要なイベントだけを購読してください。各イベントにはメッセージID、受信者、タイムスタンプが含まれるため、送信したメッセージと照合できます。

ペイロードの例

ペイロードは、POSTリクエストで送られるJSONです。ここに示す値は例にすぎません。

{
  "event": "delivered",
  "message_id": "msg_123",
  "recipient": "you@example.com",
  "timestamp": "2026-01-15T10:30:00Z"
}

署名を検証

URLを知っていれば誰でもPOSTできてしまうため、すべてのリクエストを検証してください。署名シークレットを使って生のリクエスト本文のHMACを計算し、署名ヘッダーの値と定数時間比較で照合します。一致しないリクエストは拒否してください。ヘッダー名とアルゴリズムは、ダッシュボードの署名シークレットと併せて表示されます。

const crypto = require("crypto");
function valid(rawBody, received, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

すばやく応答する

イベントを保存したらすぐに2xxステータスを返し、実際の処理はあとでキューで行ってください。エンドポイントが遅い、または失敗していると、再試行が発生し、ほかのイベントが遅れる原因になります。

重複と順序の前後を想定する

失敗した配信は再試行されるため、同じイベントが複数回届くことや、順序が前後して届くことがあります。メッセージIDとイベントタイプを使ってハンドラーを冪等にし、到着時刻ではなくイベントのタイムスタンプを使ってください。

本番前にテストする

エンドポイントをリクエストインスペクターや開発マシンへのトンネルに向け、テストメッセージを送信して、実際のトラフィックで署名を検証できることを確認してください。