SendGrid can be configured to send events like bounces and click tracking to a URL of your choice via their Webhooks feature. This post describes how to configure an AWS Lambda function to process these SendGrid events. By using Lambda you can easily handle the large amount of traffic SendGrid Webhooks can generate, while keeping costs and system administration work to a minimum.

First you want to create a Lambda function on AWS and expose it via an API Gateway endpoint. The simplest way to do this is to choose a function blueprint such as microservice-http-endpoint so that the endpoint will be configured for you during the Lambda function creation. Alternatively you can go to the API Endpoints tab in the Lambda console later to create an endpoint. The important endpoint settings to ensure it can be accessed via SendGrid Webhooks are:

  • API endpoint type: API Gateway
  • Method: POST
  • Security: Open

For the Lambda function, I’ve provided a trivial NodeJS example that simply verifies the SendGrid event type is one it is interested in, and then logs the event. If all you want is a log of all SendGrid events in AWS CloudWatch Logs then this would suffice.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
 
console.log('Loading function');

exports.handler = function(event, context) {
  console.log('Received event:', JSON.stringify(event, null, 2));
  var eventTypes = ["delivered", "open", "click", "bounce", 
                    "dropped", "spamreport", "unsubscribe"];

  for (var i = 0; i < event.length; i++) {
    var message = event[i];

    if (eventTypes.indexOf(message.event) > -1) {
      continue;
    }

    console.log('Received event:', JSON.stringify(message, null, 2));
  }

  context.done();
};

Now copy the API endpoint URL provided in the Lambda console and login to your SendGrid account. In the Webhooks section of your SendGrid account settings paste the endpoint URL and enable the events you are interested in. Now your Lambda function should begin to receive SendGrid Webhook events.