Rate this page:

Troubleshooting the Event Webhook

General troubleshooting

Considerations for troubleshooting your Event Webhook instance:

  • Start by making sure your web server is returning a 2xx response to our servers. Any other response type will result in our server retrying a POST 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.
  • Next, make sure you are not blocking our IPs that are trying to POST to your server. Our IPs change often since we constantly add more machines.
  • http://httpresponder.com/ is a helpful tool for debugging webhooks.
  • You can use the Test Your Integration feature within the Event Notification Setting on the Settings > Mail Settings page in the SendGrid UI to send simulated events to your callback URL. This will not work if you have basic authentication set in your endpoint URL. You can also send a POST from a shell using cURL - this will give you the full response your server is returning including the HTTP headers:
curl -X POST -H "Content-Type: application/json" -d '[{"email":"john.doe@sendgrid.com","timestamp":1337197600,"smtp-id":"<4FB4041F.6080505@sendgrid.com>","event":"processed"},{"email":"john.doe@sendgrid.com","timestamp":1337966815,"category":"newuser","event":"click","url":"https://sendgrid.com"},{"email":"john.doe@sendgrid.com","timestamp":1337969592,"smtp-id":"<20120525181309.C1A9B40405B3@Example-Mac.local>","event":"processed"}]'
  • If you're not getting a response from your server, follow the steps in Getting started with the Event Webhook to test your SendGrid instance with Webhook tester. You could also use tools like ngrok, or Runscope.

Common issues

Duplicate events

It is possible to see duplicate events in the data posted by the Event Webhook.

We recommend that you use some form of deduplication when processing or storing your Event Webhook data using the sg_event_id as a differentiator since this ID is unique for every event where sg_event_id is present.

The sg_event_id is a string up to 100 characters that is Base64url encoded.

Additional Resources

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

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

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more