@mailhooks/sdk 1.0.5 → 1.1.3

package/README.md

@@ -211,6 +211,122 @@ try {
 - **404 Not Found**: Resource not found
 - **429 Too Many Requests**: Rate limit exceeded
 
+## Webhook Signature Verification
+
+When you create a webhook in Mailhooks, you receive a secret that can be used to verify that incoming webhook requests are genuinely from Mailhooks. Each webhook request includes an `X-Webhook-Signature` header containing an HMAC-SHA256 signature of the request body.
+
+### Verifying Signatures
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload } from '@mailhooks/sdk';
+
+// Express.js example - IMPORTANT: Use raw body parser for signature verification
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.headers['x-webhook-signature'] as string;
+  const payload = req.body.toString();
+
+  // Verify the signature using your webhook secret
+  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+    console.error('Invalid webhook signature');
+    return res.status(401).send('Invalid signature');
+  }
+
+  // Parse the verified payload
+  const event = parseWebhookPayload(payload);
+
+  console.log(`Received email from ${event.from}: ${event.subject}`);
+
+  // Process the webhook...
+  res.status(200).send('OK');
+});
+```
+
+### Webhook Payload
+
+The webhook payload contains the following fields:
+
+```typescript
+interface WebhookPayload {
+  id: string;           // Unique email ID
+  from: string;         // Sender email address
+  to: string[];         // Array of recipient addresses
+  subject: string;      // Email subject
+  body: string;         // Plain text body
+  html?: string;        // HTML body (if available)
+  attachments: Array<{  // Attachment metadata
+    filename: string;
+    contentType: string;
+    size: number;
+  }>;
+  receivedAt: string;   // ISO 8601 timestamp
+
+  // Email authentication results
+  spfResult?: 'pass' | 'fail' | 'softfail' | 'neutral' | 'none';
+  dkimResult?: 'pass' | 'fail' | 'none' | 'temperror' | 'permerror';
+  dmarcResult?: 'pass' | 'fail' | 'none' | 'temperror' | 'permerror';
+  authSummary?: 'pass' | 'fail' | 'partial';
+
+  // Spam detection
+  spamScore?: number;   // 0.0 to 1.0
+  isSpam?: boolean;
+}
+```
+
+### Security Best Practices
+
+1. **Always verify signatures** before processing webhook data
+2. **Use the raw request body** for signature verification (not parsed JSON)
+3. **Store secrets securely** in environment variables, not in code
+4. **Use HTTPS** for your webhook endpoint
+5. **Respond quickly** - return 200 OK before doing heavy processing
+
+### Framework Examples
+
+#### Next.js API Route
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload } from '@mailhooks/sdk';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(request: NextRequest) {
+  const payload = await request.text();
+  const signature = request.headers.get('x-webhook-signature') || '';
+
+  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
+  }
+
+  const event = parseWebhookPayload(payload);
+  // Process event...
+
+  return NextResponse.json({ received: true });
+}
+```
+
+#### Fastify
+
+```typescript
+import { verifyWebhookSignature, parseWebhookPayload } from '@mailhooks/sdk';
+
+fastify.post('/webhook', {
+  config: {
+    rawBody: true, // Enable raw body
+  },
+}, async (request, reply) => {
+  const signature = request.headers['x-webhook-signature'] as string;
+  const payload = request.rawBody?.toString() || '';
+
+  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+    return reply.status(401).send({ error: 'Invalid signature' });
+  }
+
+  const event = parseWebhookPayload(payload);
+  // Process event...
+
+  return { received: true };
+});
+```
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { Mailhooks } from './mailhooks';
 export { EmailsResource } from './resources/emails';
 export * from './types';
+export { verifyWebhookSignature, parseWebhookPayload, constructSignature, type WebhookPayload, } from './webhooks';
 import { Mailhooks } from './mailhooks';
 export default Mailhooks;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,cAAc,SAAS,CAAC;AAGxB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,eAAe,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,cAAc,SAAS,CAAC;AAGxB,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,eAAe,SAAS,CAAC"}

package/dist/index.js

@@ -14,12 +14,17 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EmailsResource = exports.Mailhooks = void 0;
+exports.constructSignature = exports.parseWebhookPayload = exports.verifyWebhookSignature = exports.EmailsResource = exports.Mailhooks = void 0;
 var mailhooks_1 = require("./mailhooks");
 Object.defineProperty(exports, "Mailhooks", { enumerable: true, get: function () { return mailhooks_1.Mailhooks; } });
 var emails_1 = require("./resources/emails");
 Object.defineProperty(exports, "EmailsResource", { enumerable: true, get: function () { return emails_1.EmailsResource; } });
 __exportStar(require("./types"), exports);
+// Webhook verification utilities
+var webhooks_1 = require("./webhooks");
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhooks_1.verifyWebhookSignature; } });
+Object.defineProperty(exports, "parseWebhookPayload", { enumerable: true, get: function () { return webhooks_1.parseWebhookPayload; } });
+Object.defineProperty(exports, "constructSignature", { enumerable: true, get: function () { return webhooks_1.constructSignature; } });
 // Default export for convenience
 const mailhooks_2 = require("./mailhooks");
 exports.default = mailhooks_2.Mailhooks;

package/dist/webhooks.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Webhook payload sent by Mailhooks when an email is received.
+ */
+export interface WebhookPayload {
+    /** Unique email ID */
+    id: string;
+    /** Sender email address */
+    from: string;
+    /** Array of recipient email addresses */
+    to: string[];
+    /** Email subject line */
+    subject: string;
+    /** Plain text body of the email */
+    body: string;
+    /** HTML body of the email (if available) */
+    html?: string;
+    /** Array of attachment metadata */
+    attachments: Array<{
+        filename: string;
+        contentType: string;
+        size: number;
+    }>;
+    /** ISO 8601 timestamp when the email was received */
+    receivedAt: string;
+    /** SPF authentication result */
+    spfResult?: 'pass' | 'fail' | 'softfail' | 'neutral' | 'none';
+    /** DKIM authentication result */
+    dkimResult?: 'pass' | 'fail' | 'none' | 'temperror' | 'permerror';
+    /** DMARC authentication result */
+    dmarcResult?: 'pass' | 'fail' | 'none' | 'temperror' | 'permerror';
+    /** Overall authentication summary */
+    authSummary?: 'pass' | 'fail' | 'partial';
+    /** Email headers as key-value pairs */
+    headers?: Record<string, string>;
+    /** Authentication diagnostic details */
+    authDiagnostics?: {
+        spf: {
+            clientIp: string;
+            domain: string;
+            record?: string;
+            helo?: string;
+        } | null;
+        dkim: Array<{
+            domain: string;
+            selector?: string;
+            algorithm?: string;
+            aligned?: boolean;
+            result: string;
+        }>;
+        dmarc: {
+            domain: string;
+            policy: string;
+            record?: string;
+            alignment: {
+                spf: {
+                    result: string | false;
+                    strict: boolean;
+                };
+                dkim: {
+                    result: string | false;
+                    strict: boolean;
+                };
+            };
+        } | null;
+    };
+}
+/**
+ * Verifies a webhook signature using HMAC-SHA256.
+ *
+ * Each webhook request from Mailhooks includes an `X-Webhook-Signature` header
+ * containing a hex-encoded HMAC-SHA256 signature of the request body.
+ *
+ * @param payload - The raw request body as a string or Buffer
+ * @param signature - The signature from the `X-Webhook-Signature` header
+ * @param secret - Your webhook secret (starts with `whsec_`)
+ * @returns `true` if the signature is valid, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@mailhooks/sdk';
+ *
+ * // Express.js with raw body parser
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const payload = req.body.toString();
+ *
+ *   if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(payload);
+ *   // Process the webhook...
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+export declare function verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;
+/**
+ * Parses a webhook payload from a JSON string.
+ *
+ * @param body - The raw request body as a string
+ * @returns The parsed webhook payload
+ * @throws {SyntaxError} If the body is not valid JSON
+ *
+ * @example
+ * ```typescript
+ * import { parseWebhookPayload } from '@mailhooks/sdk';
+ *
+ * const payload = parseWebhookPayload(req.body.toString());
+ * console.log(`Received email from ${payload.from}: ${payload.subject}`);
+ * ```
+ */
+export declare function parseWebhookPayload(body: string): WebhookPayload;
+/**
+ * Constructs the expected signature for a webhook payload.
+ * Useful for debugging or manual verification.
+ *
+ * @param payload - The raw request body as a string or Buffer
+ * @param secret - Your webhook secret
+ * @returns The expected HMAC-SHA256 signature as a hex string
+ */
+export declare function constructSignature(payload: string | Buffer, secret: string): string;
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,EAAE,EAAE,MAAM,EAAE,CAAC;IACb,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,WAAW,EAAE,KAAK,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAC9D,iCAAiC;IACjC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;IAClE,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,CAAC;IACnE,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAC1C,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,wCAAwC;IACxC,eAAe,CAAC,EAAE;QAChB,GAAG,EAAE;YACH,QAAQ,EAAE,MAAM,CAAC;YACjB,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,IAAI,CAAC,EAAE,MAAM,CAAC;SACf,GAAG,IAAI,CAAC;QACT,IAAI,EAAE,KAAK,CAAC;YACV,MAAM,EAAE,MAAM,CAAC;YACf,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,OAAO,CAAC,EAAE,OAAO,CAAC;YAClB,MAAM,EAAE,MAAM,CAAC;SAChB,CAAC,CAAC;QACH,KAAK,EAAE;YACL,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,EAAE,MAAM,CAAC;YACf,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,SAAS,EAAE;gBACT,GAAG,EAAE;oBAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;oBAAC,MAAM,EAAE,OAAO,CAAA;iBAAE,CAAC;gBACjD,IAAI,EAAE;oBAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;oBAAC,MAAM,EAAE,OAAO,CAAA;iBAAE,CAAC;aACnD,CAAC;SACH,GAAG,IAAI,CAAC;KACV,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAqBT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,EAAE,MAAM,GACb,MAAM,CAER"}

package/dist/webhooks.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.parseWebhookPayload = parseWebhookPayload;
+exports.constructSignature = constructSignature;
+const crypto_1 = require("crypto");
+/**
+ * Verifies a webhook signature using HMAC-SHA256.
+ *
+ * Each webhook request from Mailhooks includes an `X-Webhook-Signature` header
+ * containing a hex-encoded HMAC-SHA256 signature of the request body.
+ *
+ * @param payload - The raw request body as a string or Buffer
+ * @param signature - The signature from the `X-Webhook-Signature` header
+ * @param secret - Your webhook secret (starts with `whsec_`)
+ * @returns `true` if the signature is valid, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@mailhooks/sdk';
+ *
+ * // Express.js with raw body parser
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const payload = req.body.toString();
+ *
+ *   if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET!)) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(payload);
+ *   // Process the webhook...
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+function verifyWebhookSignature(payload, signature, secret) {
+    if (!payload || !signature || !secret) {
+        return false;
+    }
+    // Normalize and validate signature format (should be 64 hex chars for SHA256)
+    const normalizedSignature = signature.trim().toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(normalizedSignature)) {
+        return false;
+    }
+    const expectedSignature = (0, crypto_1.createHmac)('sha256', secret)
+        .update(payload)
+        .digest('hex');
+    // Use timing-safe comparison to prevent timing attacks
+    // Both buffers are guaranteed to be 32 bytes (64 hex chars)
+    return (0, crypto_1.timingSafeEqual)(Buffer.from(normalizedSignature, 'hex'), Buffer.from(expectedSignature, 'hex'));
+}
+/**
+ * Parses a webhook payload from a JSON string.
+ *
+ * @param body - The raw request body as a string
+ * @returns The parsed webhook payload
+ * @throws {SyntaxError} If the body is not valid JSON
+ *
+ * @example
+ * ```typescript
+ * import { parseWebhookPayload } from '@mailhooks/sdk';
+ *
+ * const payload = parseWebhookPayload(req.body.toString());
+ * console.log(`Received email from ${payload.from}: ${payload.subject}`);
+ * ```
+ */
+function parseWebhookPayload(body) {
+    return JSON.parse(body);
+}
+/**
+ * Constructs the expected signature for a webhook payload.
+ * Useful for debugging or manual verification.
+ *
+ * @param payload - The raw request body as a string or Buffer
+ * @param secret - Your webhook secret
+ * @returns The expected HMAC-SHA256 signature as a hex string
+ */
+function constructSignature(payload, secret) {
+    return (0, crypto_1.createHmac)('sha256', secret).update(payload).digest('hex');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mailhooks/sdk",
-  "version": "1.0.5",
+  "version": "1.1.3",
   "description": "TypeScript SDK for Mailhooks API",
   "publishConfig": {
     "access": "public"