@bernierllc/email-webhook-events 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @bernierllc/email-webhook-events
+
+## 1.0.1
+
+### Patch Changes
+
+- [`c45c75c`](https://github.com/bernierllc/tools/commit/c45c75ce2db9cc9f45fe1be6c73e8018a427727c) - Migrate test infrastructure from Jest to Vitest and add integration testing support
+  - Switch from Jest to Vitest for improved ESM compatibility
+  - Add integration test infrastructure using ngrok for real SendGrid webhook testing
+  - Add @bernierllc/email-manager as dependency for integration tests
+  - Capture real webhook payloads for accurate test fixtures
+  - Update README with integration testing documentation

package/README.md

@@ -321,6 +321,48 @@ EMAIL_WEBHOOK_RATE_LIMIT_ENABLED=false
 EMAIL_WEBHOOK_RATE_LIMIT_MAX_PER_SECOND=100
 ```
 
+## Integration Testing
+
+This package includes integration tests that use real SendGrid webhooks.
+
+### Prerequisites
+
+1. SendGrid account with API key
+2. Paid ngrok account with auth token
+3. Test email address
+4. `.env.test` file configured with:
+   - `SENDGRID_API_KEY`
+   - `SENDGRID_WEBHOOK_SECRET` (optional)
+   - `TEST_EMAIL`
+   - `NGROK_AUTH_TOKEN`
+   - `NGROK_RESERVED_DOMAIN` (optional, for consistent URLs)
+   - `WEBHOOK_SERVER_PORT` (optional, defaults to 3000)
+
+### Running Integration Tests
+
+1. Ensure `.env.test` file is configured with all required variables
+2. Set `RUN_INTEGRATION_TESTS=true` environment variable
+3. Configure SendGrid webhook URL (first time only, or use reserved domain):
+   - Run test once to get webhook URL from output, or
+   - Use reserved domain: `https://your-reserved-domain.ngrok.io/webhooks/sendgrid`
+   - Go to SendGrid dashboard → Settings → Mail Settings → Event Webhook
+   - Set webhook URL and enable all event types
+4. Run tests: `npm test -- sendgrid-webhook-integration`
+
+Tests automatically:
+- Start webhook server
+- Create ngrok tunnel (programmatically)
+- Send test emails via @bernierllc/email-manager
+- Capture and process webhooks
+- Save payloads to `__tests__/fixtures/sendgrid-webhooks/`
+
+### Captured Payloads
+
+Real webhook payloads are captured in `__tests__/fixtures/sendgrid-webhooks/`
+and used to generate accurate mocks for unit tests.
+
+See `__tests__/fixtures/sendgrid-webhooks/README.md` for more details.
+
 ## Integration Status
 
 - **Logger**: integrated - Uses MockLogger (pending @bernierllc/logger publication)

package/__tests__/fixtures/sendgrid-webhooks/README.md

@@ -0,0 +1,63 @@
+# SendGrid Webhook Fixtures
+
+This directory contains webhook payloads based on REAL SendGrid webhook structures captured during integration testing.
+
+> ⚠️ **SANITIZED DATA**: All email addresses, IPs, message IDs, signatures, and other identifiable data have been replaced with fake test values. The **structure** matches real SendGrid payloads but all values are safe for version control.
+
+## Structure
+
+Each event type has its own JSON file containing an array of captured webhook payloads:
+
+- `delivered.json` - Email delivered events
+- `open.json` - Email opened events
+- `click.json` - Link clicked events
+- `bounce.json` - Email bounced events
+- `spamreport.json` - Spam complaint events
+- `unsubscribe.json` - Unsubscribe events
+- `deferred.json` - Email delivery deferred events
+- `dropped.json` - Email dropped events
+
+## File Format
+
+Each file contains an array of captured webhook objects:
+
+```json
+[
+  {
+    "headers": {
+      "x-twilio-email-event-webhook-signature": "...",
+      "content-type": "application/json",
+      ...
+    },
+    "body": {
+      "event": "delivered",
+      "email": "user@example.com",
+      "timestamp": 1234567890,
+      "sg_message_id": "...",
+      ...
+    },
+    "timestamp": "2025-01-27T12:00:00.000Z",
+    "eventType": "delivered"
+  }
+]
+```
+
+## Usage
+
+These fixtures are automatically generated during integration tests and can be used to:
+
+1. Generate accurate mocks for unit tests
+2. Validate webhook payload structure
+3. Test normalizer implementations with real data
+4. Debug webhook processing issues
+
+## Generation
+
+Fixtures are automatically captured when running integration tests:
+
+```bash
+npm test -- sendgrid-webhook-integration
+```
+
+The webhook server automatically saves all received webhooks to the appropriate fixture files.
+

package/__tests__/fixtures/sendgrid-webhooks/deferred.json

@@ -0,0 +1,31 @@
+[
+  {
+    "headers": {
+      "host": "example-webhook.ngrok.app",
+      "user-agent": "SendGrid Event API",
+      "content-length": "498",
+      "accept-encoding": "gzip",
+      "content-type": "application/json;charset=utf-8",
+      "x-forwarded-for": "192.0.2.30",
+      "x-forwarded-host": "example-webhook.ngrok.app",
+      "x-forwarded-proto": "https",
+      "x-twilio-email-event-webhook-signature": "FAKE_SIGNATURE_MEQCIG5UlgMJ_DO_NOT_USE_IN_PRODUCTION=",
+      "x-twilio-email-event-webhook-timestamp": "1700000300"
+    },
+    "body": {
+      "attempt": "2",
+      "domain": "example.com",
+      "email": "deferred-recipient@example.com",
+      "event": "deferred",
+      "from": "Test Sender <sender@example.com>",
+      "response": "temporarily unable to deliver - server busy, please retry later",
+      "sg_event_id": "FAKE_DEFERRED_EVENT_001",
+      "sg_message_id": "FAKE_MSG_DEFERRED_001.recvd-1234567890-pqrst-1-1234567B-14.0",
+      "smtp-id": "<FAKE_MSG_DEFERRED_001@geopod-ismtpd-test>",
+      "timestamp": 1700000300,
+      "tls": 0
+    },
+    "timestamp": "2025-01-01T12:05:00.000Z",
+    "eventType": "deferred"
+  }
+]

package/__tests__/fixtures/sendgrid-webhooks/delivered.json

@@ -0,0 +1,83 @@
+[
+  {
+    "headers": {
+      "host": "example-webhook.ngrok.app",
+      "user-agent": "SendGrid Event API",
+      "content-length": "405",
+      "accept-encoding": "gzip",
+      "content-type": "application/json;charset=utf-8",
+      "x-forwarded-for": "192.0.2.1",
+      "x-forwarded-host": "example-webhook.ngrok.app",
+      "x-forwarded-proto": "https",
+      "x-twilio-email-event-webhook-signature": "FAKE_SIGNATURE_MEUCIB5bSBgVWU_DO_NOT_USE_IN_PRODUCTION=",
+      "x-twilio-email-event-webhook-timestamp": "1700000000"
+    },
+    "body": {
+      "email": "test-recipient@example.com",
+      "event": "delivered",
+      "ip": "192.0.2.10",
+      "response": "250 2.0.0 OK  1700000000 example-mail-server.example.com - gsmtp",
+      "sg_event_id": "FAKE_DELIVERED_EVENT_001",
+      "sg_message_id": "FAKE_MSG_001.recvd-1234567890-abcde-1-12345678-37.0",
+      "smtp-id": "<FAKE_MSG_001@geopod-ismtpd-test>",
+      "timestamp": 1700000000,
+      "tls": 1
+    },
+    "timestamp": "2025-01-01T12:00:00.000Z",
+    "eventType": "delivered"
+  },
+  {
+    "headers": {
+      "host": "example-webhook.ngrok.app",
+      "user-agent": "SendGrid Event API",
+      "content-length": "405",
+      "accept-encoding": "gzip",
+      "content-type": "application/json;charset=utf-8",
+      "x-forwarded-for": "192.0.2.2",
+      "x-forwarded-host": "example-webhook.ngrok.app",
+      "x-forwarded-proto": "https",
+      "x-twilio-email-event-webhook-signature": "FAKE_SIGNATURE_MEUCICpeBdSY_DO_NOT_USE_IN_PRODUCTION=",
+      "x-twilio-email-event-webhook-timestamp": "1700000100"
+    },
+    "body": {
+      "email": "test-recipient@example.com",
+      "event": "delivered",
+      "ip": "192.0.2.11",
+      "response": "250 2.0.0 OK  1700000100 example-mail-server.example.com - gsmtp",
+      "sg_event_id": "FAKE_DELIVERED_EVENT_002",
+      "sg_message_id": "FAKE_MSG_002.recvd-1234567890-fghij-1-12345679-10.0",
+      "smtp-id": "<FAKE_MSG_002@geopod-ismtpd-test>",
+      "timestamp": 1700000100,
+      "tls": 1
+    },
+    "timestamp": "2025-01-01T12:01:40.000Z",
+    "eventType": "delivered"
+  },
+  {
+    "headers": {
+      "host": "example-webhook.ngrok.app",
+      "user-agent": "SendGrid Event API",
+      "content-length": "405",
+      "accept-encoding": "gzip",
+      "content-type": "application/json;charset=utf-8",
+      "x-forwarded-for": "192.0.2.3",
+      "x-forwarded-host": "example-webhook.ngrok.app",
+      "x-forwarded-proto": "https",
+      "x-twilio-email-event-webhook-signature": "FAKE_SIGNATURE_MEQCIAektsAA_DO_NOT_USE_IN_PRODUCTION=",
+      "x-twilio-email-event-webhook-timestamp": "1700000200"
+    },
+    "body": {
+      "email": "another-recipient@example.com",
+      "event": "delivered",
+      "ip": "192.0.2.12",
+      "response": "250 2.0.0 OK  1700000200 example-mail-server.example.com - gsmtp",
+      "sg_event_id": "FAKE_DELIVERED_EVENT_003",
+      "sg_message_id": "FAKE_MSG_003.recvd-1234567890-klmno-1-1234567A-10.0",
+      "smtp-id": "<FAKE_MSG_003@geopod-ismtpd-test>",
+      "timestamp": 1700000200,
+      "tls": 1
+    },
+    "timestamp": "2025-01-01T12:03:20.000Z",
+    "eventType": "delivered"
+  }
+]

package/__tests__/fixtures/sendgrid-webhooks/open.json

@@ -0,0 +1,83 @@
+[
+  {
+    "headers": {
+      "host": "example-webhook.ngrok.app",
+      "user-agent": "SendGrid Event API",
+      "content-length": "416",
+      "accept-encoding": "gzip",
+      "content-type": "application/json;charset=utf-8",
+      "x-forwarded-for": "192.0.2.20",
+      "x-forwarded-host": "example-webhook.ngrok.app",
+      "x-forwarded-proto": "https",
+      "x-twilio-email-event-webhook-signature": "FAKE_SIGNATURE_MEQCIHN5S5nZ_DO_NOT_USE_IN_PRODUCTION=",
+      "x-twilio-email-event-webhook-timestamp": "1700000050"
+    },
+    "body": {
+      "email": "test-recipient@example.com",
+      "event": "open",
+      "ip": "192.0.2.100",
+      "sg_content_type": "html",
+      "sg_event_id": "FAKE_OPEN_EVENT_001",
+      "sg_machine_open": false,
+      "sg_message_id": "FAKE_MSG_001.recvd-1234567890-abcde-1-12345678-1B.0",
+      "timestamp": 1700000050,
+      "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+    },
+    "timestamp": "2025-01-01T12:00:50.000Z",
+    "eventType": "open"
+  },
+  {
+    "headers": {
+      "host": "example-webhook.ngrok.app",
+      "user-agent": "SendGrid Event API",
+      "content-length": "416",
+      "accept-encoding": "gzip",
+      "content-type": "application/json;charset=utf-8",
+      "x-forwarded-for": "192.0.2.21",
+      "x-forwarded-host": "example-webhook.ngrok.app",
+      "x-forwarded-proto": "https",
+      "x-twilio-email-event-webhook-signature": "FAKE_SIGNATURE_MEQCIFFHHjr5_DO_NOT_USE_IN_PRODUCTION=",
+      "x-twilio-email-event-webhook-timestamp": "1700000150"
+    },
+    "body": {
+      "email": "test-recipient@example.com",
+      "event": "open",
+      "ip": "192.0.2.101",
+      "sg_content_type": "html",
+      "sg_event_id": "FAKE_OPEN_EVENT_002",
+      "sg_machine_open": false,
+      "sg_message_id": "FAKE_MSG_002.recvd-1234567890-fghij-1-12345679-10.0",
+      "timestamp": 1700000150,
+      "useragent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+    },
+    "timestamp": "2025-01-01T12:02:30.000Z",
+    "eventType": "open"
+  },
+  {
+    "headers": {
+      "host": "example-webhook.ngrok.app",
+      "user-agent": "SendGrid Event API",
+      "content-length": "366",
+      "accept-encoding": "gzip",
+      "content-type": "application/json;charset=utf-8",
+      "x-forwarded-for": "192.0.2.22",
+      "x-forwarded-host": "example-webhook.ngrok.app",
+      "x-forwarded-proto": "https",
+      "x-twilio-email-event-webhook-signature": "FAKE_SIGNATURE_MEUCIQC7bY6P_DO_NOT_USE_IN_PRODUCTION=",
+      "x-twilio-email-event-webhook-timestamp": "1700000250"
+    },
+    "body": {
+      "email": "another-recipient@example.com",
+      "event": "open",
+      "ip": "192.0.2.102",
+      "sg_content_type": "html",
+      "sg_event_id": "FAKE_OPEN_EVENT_003",
+      "sg_machine_open": true,
+      "sg_message_id": "FAKE_MSG_003.recvd-1234567890-klmno-1-1234567A-10.0",
+      "timestamp": 1700000250,
+      "useragent": "Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)"
+    },
+    "timestamp": "2025-01-01T12:04:10.000Z",
+    "eventType": "open"
+  }
+]

package/__tests__/integration/ngrok-tunnel-manager.ts

@@ -0,0 +1,88 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { connect, disconnect } from '@ngrok/ngrok';
+
+export interface NgrokTunnelConfig {
+  port: number;
+  domain?: string; // Reserved domain (paid account feature)
+  authtoken?: string;
+}
+
+export class NgrokTunnelManager {
+  private listener: any;
+  private publicUrl: string | null = null;
+
+  async start(config: NgrokTunnelConfig): Promise<string> {
+    const connectOptions: any = {
+      addr: config.port,
+      authtoken: config.authtoken || process.env.NGROK_AUTH_TOKEN
+    };
+
+    // Use reserved domain if available (paid account feature)
+    if (config.domain) {
+      connectOptions.domain = config.domain;
+    }
+
+    try {
+      // Disconnect any existing tunnels first (in case of previous failed runs)
+      try {
+        await disconnect();
+        console.log('Disconnected existing ngrok tunnels');
+      } catch {
+        // Ignore errors if no tunnels exist
+      }
+
+      this.listener = await connect(connectOptions);
+      this.publicUrl = this.listener.url();
+      
+      if (!this.publicUrl) {
+        throw new Error('Failed to get ngrok tunnel URL');
+      }
+      
+      console.log(`ngrok tunnel established: ${this.publicUrl}`);
+      return this.publicUrl;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to start ngrok tunnel: ${errorMessage}`);
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (this.listener) {
+      try {
+        // Use disconnect with the URL, or close the listener directly
+        const url = this.listener.url();
+        if (url) {
+          const { disconnect } = await import('@ngrok/ngrok');
+          await disconnect(url);
+        }
+        this.listener = null;
+        this.publicUrl = null;
+        console.log('ngrok tunnel closed');
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.warn(`Error closing ngrok tunnel: ${errorMessage}`);
+      }
+    }
+  }
+
+  getUrl(): string | null {
+    return this.publicUrl;
+  }
+
+  // Get tunnel statistics (paid account feature)
+  async getStats(): Promise<any> {
+    if (!this.listener) {
+      throw new Error('Tunnel not started');
+    }
+    // Access tunnel metrics via ngrok API
+    return this.listener;
+  }
+}
+

package/__tests__/integration/sendgrid-webhook-integration.test.ts

@@ -0,0 +1,267 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+/**
+ * SendGrid Webhook Integration Tests
+ *
+ * These tests use REAL SendGrid API and webhooks to:
+ * - Send emails via @bernierllc/email-manager
+ * - Receive webhooks from SendGrid via ngrok tunnel
+ * - Process webhooks through @bernierllc/email-webhook-events
+ * - Capture real webhook payloads for mock generation
+ *
+ * Prerequisites:
+ * - .env.test file with valid API keys and configuration
+ * - SendGrid webhook URL configured to ngrok URL
+ * - RUN_INTEGRATION_TESTS=true environment variable set
+ *
+ * Run with: npm test -- sendgrid-webhook-integration
+ */
+
+import * as dotenv from 'dotenv';
+import * as path from 'path';
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
+import { EmailManager } from '@bernierllc/email-manager';
+import { EmailWebhookEventsService, EmailProvider, EmailEventType } from '../../src/index';
+import { WebhookTestServer, CapturedWebhook } from './webhook-server';
+import { NgrokTunnelManager } from './ngrok-tunnel-manager';
+
+// Load test environment variables from .env.test (at repo root)
+dotenv.config({ path: path.join(__dirname, '..', '..', '..', '..', '..', '.env.test') });
+
+// Skip these tests if not explicitly enabled or if required env vars are missing
+const SKIP_INTEGRATION_TESTS = 
+  !process.env.RUN_INTEGRATION_TESTS || 
+  !process.env.SENDGRID_API_KEY ||
+  !process.env.SENDGRID_FROM_EMAIL ||
+  !process.env.NGROK_AUTH_TOKEN ||
+  !process.env.TEST_EMAIL;
+
+const describeOrSkip = SKIP_INTEGRATION_TESTS ? describe.skip : describe;
+
+describeOrSkip('SendGrid Webhook Integration Tests', () => {
+  let webhookServer: WebhookTestServer;
+  let ngrokTunnel: NgrokTunnelManager;
+  let webhookUrl: string;
+  let emailManager: EmailManager;
+  let webhookService: EmailWebhookEventsService;
+
+  beforeAll(async () => {
+    // Start webhook server
+    const port = parseInt(process.env.WEBHOOK_SERVER_PORT || '3000', 10);
+    webhookServer = new WebhookTestServer(port);
+    await webhookServer.start();
+
+    // Start ngrok tunnel programmatically
+    ngrokTunnel = new NgrokTunnelManager();
+    webhookUrl = await ngrokTunnel.start({
+      port,
+      domain: process.env.NGROK_RESERVED_DOMAIN,
+      authtoken: process.env.NGROK_AUTH_TOKEN
+    });
+    
+    console.log(`\n📡 Webhook URL: ${webhookUrl}/webhooks/sendgrid`);
+    console.log(`📋 Configure SendGrid webhook URL to: ${webhookUrl}/webhooks/sendgrid\n`);
+
+    // Initialize email manager
+    emailManager = new EmailManager({
+      providers: [],
+      scheduling: { enabled: false } // Disable scheduler for tests
+    });
+
+    // Manually add provider and await to ensure it's registered before sending
+    const addResult = await emailManager.addProvider({
+      id: 'sendgrid-test',
+      name: 'SendGrid Test',
+      type: 'sendgrid',
+      config: {
+        apiKey: process.env.SENDGRID_API_KEY!,
+        fromEmail: process.env.SENDGRID_FROM_EMAIL!,
+        fromName: 'Webhook Integration Test'
+      },
+      isActive: true,
+      priority: 1
+    });
+    
+    if (!addResult.success) {
+      throw new Error(`Failed to add SendGrid provider: ${addResult.errors?.join(', ')}`);
+    }
+    
+    console.log('✅ SendGrid provider added successfully');
+
+    // Initialize webhook service
+    webhookService = new EmailWebhookEventsService({
+      providers: [{
+        provider: EmailProvider.SENDGRID,
+        enabled: true,
+        webhookUrl: '/webhooks/sendgrid',
+        secretKey: process.env.SENDGRID_WEBHOOK_SECRET || '',
+        signatureHeader: 'X-Twilio-Email-Event-Webhook-Signature',
+        signatureAlgorithm: 'sha256'
+      }],
+      persistence: { 
+        enabled: true, 
+        adapter: 'memory' 
+      },
+      analytics: { 
+        realTimeEnabled: true,
+        aggregationInterval: 5000,
+        retentionDays: 90
+      }
+    });
+    await webhookService.initialize();
+  }, 60000); // 60 second timeout for setup
+
+  afterAll(async () => {
+    await ngrokTunnel.stop();
+    await webhookServer.stop();
+  }, 30000);
+
+  beforeEach(() => {
+    webhookServer.clearCapturedWebhooks();
+  });
+
+  // Helper function to wait for webhook
+  async function waitForWebhook(
+    eventType: string,
+    timeout: number = 60000
+  ): Promise<CapturedWebhook | null> {
+    const startTime = Date.now();
+    
+    while (Date.now() - startTime < timeout) {
+      const webhooks = webhookServer.getCapturedWebhooks();
+      const matching = webhooks.find(w => w.body.event === eventType);
+      
+      if (matching) {
+        return matching;
+      }
+      
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+    
+    return null;
+  }
+
+  it('should receive and process delivered webhook', async () => {
+    const testEmail = process.env.TEST_EMAIL!;
+    
+    // Send email
+    const sendResult = await emailManager.sendEmail({
+      to: testEmail,
+      subject: 'Test Email for Webhook Testing - Delivered',
+      html: '<h1>Test</h1><p>This is a test email for delivered webhook testing.</p>',
+      text: 'Test: This is a test email for delivered webhook testing.'
+    });
+
+    expect(sendResult.success).toBe(true);
+    expect(sendResult.messageId).toBeDefined();
+
+    // Wait for webhook (with timeout)
+    const deliveredWebhook = await waitForWebhook('delivered', 60000);
+    
+    expect(deliveredWebhook).toBeDefined();
+    expect(deliveredWebhook?.body.event).toBe('delivered');
+    expect(deliveredWebhook?.body.email).toBe(testEmail);
+
+    // Process webhook through service
+    const result = await webhookService.processWebhook({
+      provider: EmailProvider.SENDGRID,
+      signature: deliveredWebhook!.headers['x-twilio-email-event-webhook-signature'] || '',
+      payload: deliveredWebhook!.body,
+      headers: deliveredWebhook!.headers
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.event).toBeDefined();
+    expect(result.event!.type).toBe(EmailEventType.DELIVERED);
+    expect(result.event!.recipient).toBe(testEmail);
+  }, 120000); // 2 minute timeout for email delivery
+
+  it('should capture webhook payload structure', async () => {
+    const testEmail = process.env.TEST_EMAIL!;
+    
+    // Send email
+    await emailManager.sendEmail({
+      to: testEmail,
+      subject: 'Test Email for Payload Capture',
+      html: '<h1>Payload Test</h1><p>Capturing webhook payload structure.</p>',
+      text: 'Payload Test: Capturing webhook payload structure.'
+    });
+
+    // Wait for delivered webhook
+    const deliveredWebhook = await waitForWebhook('delivered', 60000);
+    
+    expect(deliveredWebhook).toBeDefined();
+    
+    // Verify payload structure
+    expect(deliveredWebhook!.body).toHaveProperty('event');
+    expect(deliveredWebhook!.body).toHaveProperty('email');
+    expect(deliveredWebhook!.body).toHaveProperty('timestamp');
+    expect(deliveredWebhook!.body).toHaveProperty('sg_message_id');
+    
+    // Verify headers
+    expect(deliveredWebhook!.headers).toBeDefined();
+    
+    console.log('\n📦 Captured webhook payload structure:');
+    console.log(JSON.stringify(deliveredWebhook!.body, null, 2));
+  }, 120000);
+
+  it('should handle multiple events in single webhook', async () => {
+    const testEmail = process.env.TEST_EMAIL!;
+    
+    // Send email
+    await emailManager.sendEmail({
+      to: testEmail,
+      subject: 'Test Email for Multiple Events',
+      html: '<h1>Multiple Events</h1><p>Testing multiple webhook events.</p>',
+      text: 'Multiple Events: Testing multiple webhook events.'
+    });
+
+    // Wait for delivered webhook
+    const deliveredWebhook = await waitForWebhook('delivered', 60000);
+    
+    expect(deliveredWebhook).toBeDefined();
+    
+    // SendGrid may send multiple events in one webhook
+    // Verify we can handle both single and multiple events
+    const allWebhooks = webhookServer.getCapturedWebhooks();
+    expect(allWebhooks.length).toBeGreaterThan(0);
+  }, 120000);
+
+  // Note: Open, click, bounce, spamreport, and unsubscribe events
+  // require manual interaction or specific test conditions.
+  // These can be tested manually or with email client automation.
+  
+  it('should process webhook with signature validation', async () => {
+    const testEmail = process.env.TEST_EMAIL!;
+    
+    // Send email
+    await emailManager.sendEmail({
+      to: testEmail,
+      subject: 'Test Email for Signature Validation',
+      html: '<h1>Signature Test</h1><p>Testing webhook signature validation.</p>',
+      text: 'Signature Test: Testing webhook signature validation.'
+    });
+
+    // Wait for delivered webhook
+    const deliveredWebhook = await waitForWebhook('delivered', 60000);
+    
+    expect(deliveredWebhook).toBeDefined();
+    
+    // Verify signature header is present (if SendGrid provides it)
+    const signatureHeader = deliveredWebhook!.headers['x-twilio-email-event-webhook-signature'];
+    
+    if (signatureHeader) {
+      expect(signatureHeader).toBeDefined();
+      console.log('\n🔐 Webhook signature header present:', signatureHeader.substring(0, 20) + '...');
+    } else {
+      console.log('\n⚠️  Webhook signature header not present (may not be configured in SendGrid)');
+    }
+  }, 120000);
+});
+