fix: event webhook interface to process raw body

docs/use-cases/event-webhook.md

@@ -0,0 +1,62 @@
+First, follow the guide to [set up signature verification for event webhooks](https://sendgrid.com/docs/for-developers/tracking-events/getting-started-event-webhook-security-features/)
+
+An example of a server to process incoming event webhooks:
+```javascript
+const bodyParser = require("body-parser");
+const express = require('express');
+const functions = require("firebase-functions");
+var app = express();
+
+const {EventWebhook, EventWebhookHeader} = require('@sendgrid/eventwebhook');
+
+const verifyRequest = function (publicKey, payload, signature, timestamp) {
+  const eventWebhook = EventWebhook();
+  const ecPublicKey = eventWebhook.convertPublicKeyToECDSA(publicKey);
+  return eventWebhook.verifySignature(ecPublicKey, payload, signature, timestamp);
+}
+
+// Example using bodyParser middleware
+app.use(bodyParser.text({ type: 'application/json' }));
+app.post("/sendgrid/webhook", async (req, resp) => {
+  try {
+    const key = '<your_public_key>';
+    const signature = req.get(EventWebhookHeader.SIGNATURE());
+    const timestamp = req.get(EventWebhookHeader.TIMESTAMP());
+
+    if (verifyRequest(key, req.body, signature, timestamp)) {
+      resp.send(204);
+    } else {
+      resp.send(403);
+    }
+  } catch (error) {
+    resp.status(500).send(error);
+  }
+})
+
+// Example using firebase functions
+app.post("/sendgrid/webhook", async (req, resp) => {
+  try {
+    const signature = req.header(EventWebhookHeader.SIGNATURE());
+    const timestamp = req.header(EventWebhookHeader.TIMESTAMP());
+
+    //getConfig is mostly a wrapper to functions.config() to get cloud function configuration json
+    const key = getConfig().sendgrid.webhook_verification_key;
+
+    //Because this is a cloud function environment, we can access the original request body (not the parsed payload) on req.rawBody. 
+    //We need to cast to functions.https.Request because `rawBody` is not available on the normal express.Request object. 
+    //the rawBody is of type {Buffer}
+    const bodyPayload = (req as functions.https.Request).rawBody;
+
+    const verified = verifyRequest(key, bodyPayload, signature, timestamp);
+    logger.info("Sendgrid key verified", verified);
+    if (!verified) {
+        resp.send(403);
+        return;
+    }
+    resp.send(204);
+  } catch (error) {
+    logger.error("Failed to process webhook", error);
+    resp.status(500).send(error);
+  }
+})
+```

packages/eventwebhook/index.d.ts

@@ -1,3 +1,6 @@
-import EventWebhook = require('./src/eventwebhook');
+import {EventWebhook, EventWebhookHeader} = require('./src/eventwebhook');
 
-export = EventWebhook;
+export {
+    EventWebhook,
+    EventWebhookHeader
+};

packages/eventwebhook/src/eventwebhook.d.ts

@@ -11,12 +11,12 @@ declare class EventWebhook {
     /**
      *
      * @param {PublicKey} publicKey elliptic curve public key
-     * @param {object|string} payload event payload in the request body
+     * @param {string|Buffer} payload event payload in the request body
      * @param {string} signature value obtained from the 'X-Twilio-Email-Event-Webhook-Signature' header
      * @param {string} timestamp value obtained from the 'X-Twilio-Email-Event-Webhook-Timestamp' header
      * @return {Boolean} true or false if signature is valid
      */
-    verifySignature(publicKey: PublicKey, payload: object|string, signature: string, timestamp: string): boolean;
+    verifySignature(publicKey: PublicKey, payload: string|Buffer, signature: string, timestamp: string): boolean;
 }
 
 export = EventWebhook;

packages/eventwebhook/src/eventwebhook.js

@@ -24,18 +24,35 @@ class EventWebhook {
    * Verify signed event webhook requests.
    *
    * @param {PublicKey} publicKey elliptic curve public key
-   * @param {Object|string} payload event payload in the request body
+   * @param {string|Buffer} payload event payload in the request body
    * @param {string} signature value obtained from the 'X-Twilio-Email-Event-Webhook-Signature' header
    * @param {string} timestamp value obtained from the 'X-Twilio-Email-Event-Webhook-Timestamp' header
    * @return {Boolean} true or false if signature is valid
    */
   verifySignature(publicKey, payload, signature, timestamp) {
-    let timestampPayload = typeof payload === 'object' ? JSON.stringify(payload) : payload;
+    let timestampPayload = Buffer.isBuffer(payload) ? payload.toString() : payload;
     timestampPayload = timestamp + timestampPayload;
     const decodedSignature = Signature.fromBase64(signature);
 
     return Ecdsa.verify(timestampPayload, decodedSignature, publicKey);
   }
 }
 
-module.exports = EventWebhook;
+/*
+ * This class lists headers that get posted to the webhook. Read the docs for
+ * more details: https://sendgrid.com/docs/for-developers/tracking-events/event
+ */
+class EventWebhookHeader {
+  static SIGNATURE() {
+    return 'X-Twilio-Email-Event-Webhook-Signature';
+  }
+
+  static TIMESTAMP() {
+    return 'X-Twilio-Email-Event-Webhook-Timestamp';
+  }
+}
+
+module.exports = {
+  EventWebhook,
+  EventWebhookHeader,
+};

packages/eventwebhook/src/eventwebhook.spec.js

@@ -1,14 +1,14 @@
-const EventWebhook = require('./eventwebhook');
+const {EventWebhook, EventWebhookHeader} = require('./eventwebhook');
 
 describe('EventWebhook', () => {
   const PUBLIC_KEY = 'MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEDr2LjtURuePQzplybdC+u4CwrqDqBaWjcMMsTbhdbcwHBcepxo7yAQGhHPTnlvFYPAZFceEu/1FwCM/QmGUhA==';
   const SIGNATURE = 'MEUCIQCtIHJeH93Y+qpYeWrySphQgpNGNr/U+UyUlBkU6n7RAwIgJTz2C+8a8xonZGi6BpSzoQsbVRamr2nlxFDWYNH2j/0=';
   const TIMESTAMP = '1588788367';
-  const PAYLOAD = {
+  const PAYLOAD = JSON.stringify({
     category: 'example_payload',
     event: 'test_event',
     message_id: 'message_id',
-  };
+  });
 
   describe('#verifySignature()', () => {
     it('should verify a valid signature', () => {
@@ -58,6 +58,16 @@ describe('EventWebhook', () => {
   });
 });
 
+describe('EventWebhookHeader', () => {
+  it('sets the signature header', () => {
+    expect(EventWebhookHeader.SIGNATURE()).to.equal('X-Twilio-Email-Event-Webhook-Signature');
+  });
+
+  it('sets the timestamp header', () => {
+    expect(EventWebhookHeader.TIMESTAMP()).to.equal('X-Twilio-Email-Event-Webhook-Timestamp');
+  });
+});
+
 function verify(publicKey, payload, signature, timestamp) {
   const ew = new EventWebhook();
   const key = ew.convertPublicKeyToECDSA(publicKey);

test/typescript/eventwebhook.ts

@@ -4,10 +4,10 @@ var ew = new EventWebhook();
 const PUBLIC_KEY = "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEDr2LjtURuePQzplybdC+u4CwrqDqBaWjcMMsTbhdbcwHBcepxo7yAQGhHPTnlvFYPAZFceEu/1FwCM/QmGUhA==";
 const SIGNATURE = "MEUCIQCtIHJeH93Y+qpYeWrySphQgpNGNr/U+UyUlBkU6n7RAwIgJTz2C+8a8xonZGi6BpSzoQsbVRamr2nlxFDWYNH2j/0=";
 const TIMESTAMP = "1588788367";
-const PAYLOAD = {
+const PAYLOAD = JSON.stringify({
     event: 'test_event',
     category: 'example_payload',
     message_id: 'message_id',
-};
+});
 var key = ew.convertPublicKeyToECDSA(PUBLIC_KEY);
 console.log(ew.verifySignature(key, PAYLOAD, SIGNATURE, TIMESTAMP));