sendgrid-webhooks

SendGrid Webhooks

このスキルを使用する場面

• メール配信の追跡用にSendGridのWebhookハンドラーを設定する
• ECDSA署名の検証失敗をデバッグする
• メールイベント（バウンス、配信完了、開封、クリック、スパム報告）を処理する
• メールエンゲージメント分析を実装する

必須コード

署名検証（手動）

SendGridでは、公開鍵検証にECDSA（楕円曲線デジタル署名アルゴリズム）を使用します。

// Node.js manual verification
const crypto = require('crypto');

function verifySignature(publicKey, payload, signature, timestamp) {
  // Decode the base64 signature
  const decodedSignature = Buffer.from(signature, 'base64');

  // Create the signed content
  const signedContent = timestamp + payload;

  // Create verifier
  const verifier = crypto.createVerify('sha256');
  verifier.update(signedContent);

  // Add PEM headers if not present
  let pemKey = publicKey;
  if (!pemKey.includes('BEGIN PUBLIC KEY')) {
    pemKey = `-----BEGIN PUBLIC KEY-----\n${publicKey}\n-----END PUBLIC KEY-----`;
  }

  // Verify the signature
  return verifier.verify(pemKey, decodedSignature);
}

// Express middleware
app.post('/webhooks/sendgrid', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');
  const timestamp = req.get('X-Twilio-Email-Event-Webhook-Timestamp');

  if (!signature || !timestamp) {
    return res.status(400).send('Missing signature headers');
  }

  const publicKey = process.env.SENDGRID_WEBHOOK_VERIFICATION_KEY;
  const payload = req.body.toString();

  if (!verifySignature(publicKey, payload, signature, timestamp)) {
    return res.status(400).send('Invalid signature');
  }

  // Process events
  const events = JSON.parse(payload);
  console.log(`Received ${events.length} events`);

  res.sendStatus(200);
});

SendGrid SDKを使用する

const { EventWebhook } = require('@sendgrid/eventwebhook');

const verifyWebhook = new EventWebhook();
const publicKey = process.env.SENDGRID_WEBHOOK_VERIFICATION_KEY;

app.post('/webhooks/sendgrid', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');
  const timestamp = req.get('X-Twilio-Email-Event-Webhook-Timestamp');

  const isValid = verifyWebhook.verifySignature(
    publicKey,
    req.body,
    signature,
    timestamp
  );

  if (!isValid) {
    return res.status(400).send('Invalid signature');
  }

  // Process webhook
  res.sendStatus(200);
});

一般的なイベントタイプ

イベント	説明	用途
processed	メッセージを受信し、配信準備が完了した状態です	メール処理の追跡
delivered	メッセージが宛先に正常に配信されました	配信確認
bounce	メッセージが恒久的に拒否されました（ブロックされたメッセージの場合は type='blocked' が含まれます）	連絡先リストの更新、配信失敗への対応
deferred	一時的な配信失敗です	遅延の監視
open	受信者がメールを開封しました	エンゲージメントの追跡
click	受信者がリンクをクリックしました	リンクの追跡、CTR分析
spam report	メールがスパムとして報告されました	リストの整理、送信者の評価の維持
unsubscribe	受信者が登録を解除しました	購読ステータスの更新
group unsubscribe	受信者がグループの登録を解除しました	グループの購読設定の更新
group resubscribe	受信者がグループに再登録しました	グループの購読設定の更新

環境変数

# Your SendGrid webhook verification key (public key)
SENDGRID_WEBHOOK_VERIFICATION_KEY="MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE..."

ローカル開発

ローカルでWebhookをテストするには、Hookdeck CLIを使用します。

npx hookdeck-cli listen 3000 sendgrid --path /webhooks/sendgrid

アカウントは不要です。ローカルトンネルと、リクエストを確認できるWeb UIを利用できます。

リソース

• overview.md - SendGrid Webhookの概要と一般的なイベントタイプ
• setup.md - SendGridダッシュボードでWebhookを設定し、検証キーを取得する方法
• verification.md - ECDSA署名検証の詳細と注意点
• examples/ - Express、Next.js、FastAPI向けの完全な実装例

関連スキル

• webhook-handler-patterns - 分野横断的なパターン（冪等性、再試行、フレームワーク別ガイド）
• hookdeck-event-gateway - キューに代わるWebhookインフラストラクチャ。Webhookハンドラー向けに、配信保証、自動再試行、再生、レート制限、可観測性を提供します