SendGrid’s Event Webhook will notify a URL of your choice via HTTP POST with information about events that occur as SendGrid processes your email. You can use this data to remove unsubscribes, react to spam reports, determine unengaged recipients, identify bounced email addresses, or create advanced analytics of your email program. With Unique Arguments and Category parameters, you can insert dynamic data that will help build a sharp, clear image of your mailings.

You should set up the Event Webhook if you want to keep track of more event data than we store for you. Due to the sheer volume of email we send, we can only store so much information. Your Email Activity Feed can hold up to 30 days worth of events. After that time passes, the email event data is gone.

Getting started

To get started with the Event Webhook:

  1. Go to the Webhook tester.
  2. Copy the unique URL.
  3. In a new window, open Settings > Mail Settings in the SendGrid UI.
  4. Turn on Event Notification.
  5. In the HTTP POST URL field, paste the unique URL that you copied in step 2.
  6. Select the Event notifications you would like to test.
  7. Click the checkmark in the top corner to save these updates into your settings.
  8. Click Test Your Integration.
    This returns an HTTP POST containing a JSON array of your selected events in one request after a very short delay. Our servers send these POSTs to the URL you defined in the Event Notification app options.
  9. Go back to the Webhook tester and reload the page.
    This loads the JSON array of your selected events that you set in the last step.

The Webhook tester site has a public URL. This is usually safe for testing purposes, just make sure that you remove the webhook.site URL from your Event Notifications settings after you are done testing.

You can also update your Event Webhook mail settings using the PATCH /user/webhooks/event/settings API method, and you can test the webhook integration using the POST /user/webhooks/event/test API method.

If you want to test your webhook locally, deploy a local version of Webhook tester, or RequestBin. Other browser options are Beeceptor, or ngrok.

Next steps

Now that you understand what Event data looks like and the basics of the webhook, it’s time to evaluate your own needs for the types of events you want to store, what kind of data storage that requires, and then switch your integration from the RequestBin test to a more permanent integration.

Data Storage

Events post every 30 seconds or when the batch size reaches 768 kilobytes - whichever occurs first. This is per server, so if you send a high volume of emails, the webhook URL may receive tens or even hundreds of posts per second. Because of this, storage should be a significant consideration of the type of integration you set up.

Storage integrations are infinitely flexible, but here are some popular options:

  • Locally on your servers.
  • SendGrid’s open source Event Kit stores the data on a Heroku instance.
  • SendGrid’s partner, Keen.io provides a platform to analyze, visualize, and store SendGrid Event data. For more information about getting started with Keen IO, see the Keen.io Getting Started page.
  • You could also use Snowplow, a web open source platform that supports SendGrid and stores the data on Amazon Redshift.
  • Several open source web libraries support SendGrid’s Event Webhook. For a full list of these libraries, see the Webhook libraries section of our API Libraries list.

If your email traffic generates a lot of events, the incoming data can quickly overload a web server if not configured correctly. You can load test your endpoints with loader.io for free.

Integrating

Once you choose a storage option, follow steps 3 through 8 in Getting started to update your Settings > Mail Settings in the SendGrid UI. Update the HTTP POST URL field to your URL, and make sure you’ve selected the events that you want to receive.

The Event Webhook does not follow redirects.

If you want to receive encrypted posts, your callback URL needs to support TLS 1.2.

Additional Resources