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’ve 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:
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 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:
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.
Let us know how we’re doing! Please rate this page:
Please note, we cannot resolve account and login issues reported on GitHub. Contact support for account assistance.
Thanks for helping us improve our docs!