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 clear image of your email program.
Categories and Unique Arguments will be stored as a “Not PII” field and may be used for counting or other operations as SendGrid runs its systems. These fields generally cannot be redacted or removed. You should take care not to place PII in this field. SendGrid does not treat this data as PII, and its value may be visible to SendGrid employees, stored long-term, and may continue to be stored after you have left SendGrid’s platform.
You should set up the Event Webhook if you want to keep track of more event data that 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.
To get started with the Event Webhook:
- Go to the Webhook tester.
- Copy the unique URL.
- In a new window, open Settings > Mail Settings in the SendGrid UI.
- Turn on Event Webhook.
- In the HTTP POST URL field, paste the unique URL that you copied in step 2.
- Select the Event notifications you would like to test.
- Click the checkmark in the top corner to save these updates into your settings.
- 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.
- 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 you remove the
webhook.site URL from your Event Notifications settings after you are done testing.
If your web server does not return a 2xx response type, we will retry a POST request until we receive a 2xx response or the maximum time has expired. All events are retried at increasing intervals for up to 24 hours after the event occurs. Please note that this time limit is a rolling 24 hours, which means new failing events will receive their own 24-hour retry period.
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.
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 provides a platform to analyze, visualize, and store SendGrid Event data. For more information about getting started with Keen, see Email Event Data with Keen.
- 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.
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.