Setting Up Webhooks to Trigger Automated Emails in SendGrid

mkdir sendgrid-webhook && cd sendgrid-webhook
npm init -y
npm install express@4.18.3 @sendgrid/mail@8.1.0 dotenv@16.4.5
```

Create the following project structure:
```
sendgrid-webhook/
├── .env
├── .gitignore
├── server.js
├── mailer.js
└── routes/
    └── webhook.js

echo ".env\nnode_modules/" >> .gitignore

PORT=3000
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FROM_EMAIL=hello@yourdomain.com
FROM_NAME=Your App Name
WEBHOOK_SECRET=your_random_secret_string_min_32_chars

import 'dotenv/config';

// Fail fast — crash on startup if any required variable is missing
const required = ['SENDGRID_API_KEY', 'FROM_EMAIL', 'WEBHOOK_SECRET'];
for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`);
  }
}

export const config = {
  port:           process.env.PORT || 3000,
  sendgridApiKey: process.env.SENDGRID_API_KEY,
  fromEmail:      process.env.FROM_EMAIL,
  fromName:       process.env.FROM_NAME || 'App',
  webhookSecret:  process.env.WEBHOOK_SECRET,
};

import sgMail from '@sendgrid/mail';
import { config } from './config.js';

// Initialize the SDK once at module load
sgMail.setApiKey(config.sendgridApiKey);

/**
 * Send a transactional email via SendGrid.
 * @param {Object} options
 * @param {string} options.to         - Recipient email address
 * @param {string} options.subject    - Email subject line
 * @param {string} options.text       - Plain-text fallback body
 * @param {string} options.html       - HTML body
 * @returns {Promise<void>}
 */
export async function sendEmail({ to, subject, text, html }) {
  const msg = {
    to,
    from: {
      email: config.fromEmail,
      name:  config.fromName,
    },
    subject,
    text,
    html,
  };

  try {
    await sgMail.send(msg);
    console.log(`[mailer] Email sent to ${to} — subject: "${subject}"`);
  } catch (error) {
    // SendGrid wraps error details in error.response.body
    const detail = error.response?.body?.errors ?? error.message;
    console.error('[mailer] SendGrid error:', JSON.stringify(detail, null, 2));
    throw error; // re-throw so the caller can handle HTTP response
  }
}

import { Router }   from 'express';
import crypto       from 'crypto';
import { config }   from '../config.js';
import { sendEmail } from '../mailer.js';

const router = Router();

/**
 * Verify the incoming webhook is from a trusted source.
 * The sender must include: Authorization: Bearer <WEBHOOK_SECRET>
 */
function verifyWebhookSecret(req, res, next) {
  const authHeader = req.headers['authorization'] ?? '';
  const token      = authHeader.replace('Bearer ', '').trim();

  // Constant-time comparison prevents timing attacks
  const expected = Buffer.from(config.webhookSecret);
  const received = Buffer.from(token);

  if (
    expected.length !== received.length ||
    !crypto.timingSafeEqual(expected, received)
  ) {
    console.warn('[webhook] Unauthorized request — invalid secret');
    return res.status(401).json({ error: 'Unauthorized' });
  }

  next();
}

/**
 * Map incoming event types to email templates.
 * Extend this object to handle new event types.
 */
const EVENT_TEMPLATES = {
  'user.signup': (payload) => ({
    to:      payload.email,
    subject: `Welcome to ${config.fromName}, ${payload.name}!`,
    text:    `Hi ${payload.name}, your account is ready.`,
    html:    `<h1>Welcome, ${payload.name}!</h1><p>Your account is live. <a href="${payload.dashboardUrl}">Go to dashboard →</a></p>`,
  }),

  'payment.success': (payload) => ({
    to:      payload.email,
    subject: `Payment confirmed — $${payload.amount}`,
    text:    `Your payment of $${payload.amount} was successful. Receipt ID: ${payload.receiptId}`,
    html:    `<h2>Payment confirmed ✓</h2><p>Amount: <strong>$${payload.amount}</strong><br/>Receipt: ${payload.receiptId}</p>`,
  }),

  'password.reset': (payload) => ({
    to:      payload.email,
    subject: 'Reset your password',
    text:    `Click the link to reset your password: ${payload.resetUrl}`,
    html:    `<p>Click below to reset your password (expires in 30 min):</p><a href="${payload.resetUrl}">${payload.resetUrl}</a>`,
  }),
};

/**
 * POST /webhook/email
 * Accepts an event type + payload and triggers the matching email.
 *
 * Expected body:
 * {
 *   "event": "user.signup",
 *   "payload": { "email": "...", "name": "...", "dashboardUrl": "..." }
 * }
 */
router.post('/email', verifyWebhookSecret, async (req, res) => {
  const { event, payload } = req.body;

  // Validate required fields
  if (!event || !payload) {
    return res.status(400).json({ error: 'Missing "event" or "payload"' });
  }

  // Look up the template builder for this event
  const buildTemplate = EVENT_TEMPLATES[event];
  if (!buildTemplate) {
    return res.status(422).json({ error: `Unknown event type: "${event}"` });
  }

  // Validate that recipient email is present in payload
  if (!payload.email) {
    return res.status(400).json({ error: 'payload.email is required' });
  }

  try {
    const emailOptions = buildTemplate(payload);
    await sendEmail(emailOptions);
    return res.status(200).json({ success: true, event });
  } catch (err) {
    // Return 500 so the caller can retry
    return res.status(500).json({ error: 'Email delivery failed', detail: err.message });
  }
});

export default router;

import express      from 'express';
import { config }   from './config.js';
import webhookRouter from './routes/webhook.js';

const app = express();

// Parse JSON bodies — must come before routes
app.use(express.json());

// Health check — useful for uptime monitors and load balancers
app.get('/health', (_req, res) => res.json({ status: 'ok' }));

// Mount webhook routes
app.use('/webhook', webhookRouter);

app.listen(config.port, () => {
  console.log(`[server] Running on http://localhost:${config.port}`);
});

{
  "type": "module",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js"
  }
}

npm run dev

ngrok http 3000
```

ngrok will output a public URL like:
```
Forwarding  https://a1b2-123-456.ngrok-free.app → http://localhost:3000

curl -X POST http://localhost:3000/webhook/email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_random_secret_string_min_32_chars" \
  -d '{
    "event": "user.signup",
    "payload": {
      "email": "test@example.com",
      "name": "Jamie",
      "dashboardUrl": "https://yourapp.com/dashboard"
    }
  }'

{
  "success": true,
  "event": "user.signup"
}
```

---

#### 4c — Verify delivery in SendGrid

1. Log in to **SendGrid → Activity Feed**
2. Filter by the recipient email address
3. You should see status **Delivered** within a few seconds

Check your terminal for the log line:
```
[mailer] Email sent to test@example.com — subject: "Welcome to App, Jamie!"

# payment.success
curl -X POST http://localhost:3000/webhook/email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_random_secret_string_min_32_chars" \
  -d '{
    "event": "payment.success",
    "payload": {
      "email": "test@example.com",
      "amount": "49.00",
      "receiptId": "rcpt_abc123"
    }
  }'

# password.reset
curl -X POST http://localhost:3000/webhook/email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_random_secret_string_min_32_chars" \
  -d '{
    "event": "password.reset",
    "payload": {
      "email": "test@example.com",
      "resetUrl": "https://yourapp.com/reset?token=xyz789"
    }
  }'

// Temporarily add this to verifyWebhookSecret for debugging only
console.log('Received token bytes:', Buffer.from(token).toJSON().data);
console.log('Expected token bytes:', Buffer.from(config.webhookSecret).toJSON().data);

# 1. Authenticate your domain (SPF, DKIM, DMARC)
#    → SendGrid → Settings → Sender Authentication → Domain Authentication

# 2. Always send both text and html body — spam filters penalize HTML-only emails
#    (Already handled in mailer.js — never remove the `text` field)

# 3. Avoid spam trigger words in subject lines:
#    ❌ "FREE", "Act Now", "Guaranteed", "!!!"
#    ✅ "Your receipt from App", "Welcome to App"

# 4. Check your sending IP reputation
#    → https://senderscore.org
#    → https://mxtoolbox.com/blacklists.aspx

npm install express-rate-limit

import rateLimit from 'express-rate-limit';
app.use('/webhook', rateLimit({ windowMs: 60_000, max: 60 }));