How to Log Email Events Using SendGrid Webhooks in Node.js

Monitoring and understanding your email delivery and engagement metrics is essential for ensuring successful communication in any modern application. Whether you’re sending order confirmations, password resets, or marketing campaigns, it’s important to know the fate of your emails. This is where SendGrid Webhooks come in handy, allowing you to track email events in real-time. In this guide, you’ll learn how to log email events using SendGrid Webhooks in Node.js—a powerful yet straightforward solution that helps optimize your email performance.

What is a Webhook?

A webhook is a way for an application to provide other applications with real-time information. In the context of SendGrid, it means that SendGrid can send email event data (such as opens, clicks, bounces, and spam reports) to your application the moment they happen.

This is particularly useful because instead of polling for updates, your server simply listens for incoming HTTP POST requests from SendGrid and processes them accordingly. Easy, efficient, and near real-time!

Why Log Email Events?

Logging email events can provide deep insights into how recipients are interacting with your emails. Here are some reasons why you might want to implement this:

Monitor deliverability: Know which emails are bouncing and fix invalid addresses.
Engagement tracking: Understand how many users open or click your emails.
Improve content: Use open and click data to refine and target your campaigns.
Audit trail: Maintain a history of communication with your users for support and compliance.

Now let’s dive into how to set this up using Node.js.

Step 1: Set Up Your Node.js Project

If you haven’t already, create a new Node.js project. Use the following commands to initialize it and install the required packages:

mkdir sendgrid-webhook
cd sendgrid-webhook
npm init -y
npm install express body-parser

These will create a basic Node.js app using Express, and the body-parser module will help you parse incoming JSON data from SendGrid.

Step 2: Set Up an Express Server

Create a file named server.js and add the following code to define your server:

const express = require('express');
const bodyParser = require('body-parser');
const fs = require('fs');

const app = express();
const PORT = 3000;

app.use(bodyParser.json());

app.post('/sendgrid-events', (req, res) => {
    const events = req.body;

    events.forEach(event => {
        // Log event to console for now
        console.log(`Received event: ${event.event} for email: ${event.email}`);

        // Append event to log file
        fs.appendFileSync('email_events.log', JSON.stringify(event) + '\n');
    });

    res.status(200).send('Events received');
});

app.listen(PORT, () => {
    console.log(`Server listening on port ${PORT}`);
});

This simple server listens for POST requests at /sendgrid-events and logs each event to a local file.

Step 3: Configure SendGrid Webhook Settings

With your server set up to receive events, it’s time to connect it to SendGrid.

Log in to your SendGrid account.
Navigate to Settings > Mail Settings in the dashboard.
Scroll down to find the Event Webhook section and click Edit.
In the HTTP POST URL field, enter your public-facing server URL (e.g., https://yourdomain.com/sendgrid-events).
Select the types of events you want to receive—e.g., delivered, open, click, bounce, spam report.

Save the settings. Now SendGrid will send event data to your Express server every time one of those events occurs.

Step 4: Make Your Server Public with ngrok (for local development)

If you’re developing on your local machine, you won’t have a publicly accessible URL. You can use ngrok for this:

npm install -g ngrok
ngrok http 3000

This will give you a temporary HTTPS URL that you can use in the SendGrid settings to test your webhook during development.

Step 5: Inspect the Incoming Event Data

The webhook payload sent by SendGrid contains detailed JSON objects. Here’s an example of what a single event looks like:

{
  "email": "user@example.com",
  "timestamp": 1703479280,
  "event": "open",
  "sg_event_id": "SG.GUID",
  "sg_message_id": "SENDGRID.MESSAGE.ID"
}

Depending on your selected event types, you’ll receive many such objects in an array. You can enhance your script to parse and store this data in a database like MongoDB, PostgreSQL, or even a cloud logging service.

Step 6: Secure Your Endpoint

Webhooks are public endpoints and therefore vulnerable if not secured properly. SendGrid provides a signing key feature you can use to verify that the request was sent by them.

Go back to the Event Webhook settings in SendGrid.
Enable Event Webhook Security and generate a public/private key pair.
Use a library like crypto in Node.js to verify the signature of incoming requests using the public key.

Adding authentication and HTTPS to your webhook endpoint is a best practice for production environments.

Bonus: Display Events in a Dashboard

Now that you’re collecting email events data reliably, why stop at just writing them to a log file? You can take this a step further by building an admin dashboard that visualizes:

Recent activity (opens, clicks, bounces)
Aggregate statistics over time
Heatmaps by time of day or geography

Frontend frameworks like React or Vue.js can be integrated with charting libraries like Chart.js or D3.js to create a beautiful and functional UX for monitoring these email events.

Common Mistakes to Avoid

Invalid endpoint URL: Ensure your URL begins with “https” and is accessible publicly.
Ignoring security: Always validate the authenticity of incoming requests when handling sensitive user data.
Poor error handling: Log errors and handle malformed payloads gracefully.
Not storing timestamps in UTC: Use standardized time to enable consistent analytics.

Conclusion

Logging email events via SendGrid webhooks in Node.js is not only practical but also critical to building robust email communication systems. With just a few lines of code, you’ve empowered your app to track meaningful metrics like opens, clicks, and delivery failures in real-time.

Whether for immediate debugging or long-term analytics, integrating webhooks ensures you’re not left in the dark when things go wrong (or right). Just remember to secure your endpoints, scale your logging responsibly, and consider turning that raw data into actionable insights with a dashboard.

Email is more than just a communication method—it’s a vital link to your users. Using tools like SendGrid’s Event Webhook, you can ensure that this link is strong, reliable, and transparent.

Log and view WordPress Emails