Getting started with the Event Webhook

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.

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 Webhook.
  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 you remove the 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. Other browser options are Beeceptor, or ngrok.

Retry logic

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.

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 within 30 seconds or when the batch size reaches 768 kilobytes. 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 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 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.

Additional Resources

Rate this page:

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!