Available to Silver and higher packages or to our free demo accounts.

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. Common uses of this data are 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.

If you’d like to see how one of our customers uses the Event Webhook, check out Leveraging SendGrid’s Event API.

Setup

If you enabled the Event Webhook prior to September 6, 2013 you will see a dropdown allowing you to select Version 1, 2 or 3 of the webhook. Version 3 is the recommended option and the only option available to new users. You can read about the older versions on the Event Webhook (deprecated) page.

To setup the Event Webhook via our web interface, login and go to the apps page, click on Show Disabled Apps, click the Event Notification app, and click on settings. Check the boxes next to the type of events you want posted to your web server, then enter in the URL you have setup to receive POSTs from our servers when an event occurs.

The Event Webhook may also be setup by using our Filter Settings Endpoint.

We support basic HTTP authentication in our Event API. Those who wish to implement can provide credentials in the post event url field on the app settings page. Below is an example of the post url with authentication included.
1
http(s)://username:password@domain/foo.php
If you wish to receive encrypted posts, we require that your callback URL support SSL v2.

Requests

You will receive a HTTP POST containing a JSON array of multiple events in one request after a very short delay. These POSTs will be sent to the URL you have defined in the Event Notification app options.

Events currently post every 1 second or when the batch size reaches 1MB (one megabyte), whichever occurs first. This is per server, so the webhook URL may receive tens of posts per second.

Event POST Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
[
  {
    "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": "http://sendgrid.com"
  },
  {
    "email": "john.doe@sendgrid.com",
    "timestamp": 1337969592,
    "smtp-id": "<20120525181309.C1A9B40405B3@Example-Mac.local>",
    "event": "processed"
  }
]

You can test your endpoint by clicking the “Test Your Integration” button on the setup screen. SendGrid will send a simulated POST of events to your callback url.

SendGrid expects a 200 HTTP response to the POST, otherwise the event notification will be retried. If your URL returns a non-200 HTTP code it will be deferred and retried for 24 hours. The maximum number of deferred POSTs in the retry queue is 100,000. If the queue is full, the oldest request in the queue will be removed to make room for the newest deferred POST. Events that cannot be submitted within the maximum retry period or events removed from the defer queue will be lost.

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

Event Types

The following lists the events generated by SendGrid.

Event Criteria
Processed Message has been received and is ready to be delivered.
Dropped You may see the following drop reasons:
  • Invalid SMTPAPI header
  • Spam Content (if spam checker app enabled)
  • Unsubscribed Address
  • Bounced Address
  • Spam Reporting Address
  • Invalid
Delivered Message has been successfully delivered to the receiving server.
Deferred Recipient’s email server temporarily rejected message.
Bounce Receiving server could not or would not accept message.
Open Recipient has opened the HTML message.
Click Recipient clicked on a link within the message.
Spam Report Recipient marked message as spam.
Unsubscribe Recipient clicked on message’s subscription management link.

The following image shows where events can be generated as email is being processed:

Default Parameters for Delivery Events

The following parameters are sent with delivery events: bounce, deferred, delivered, dropped, and processed events. Some events may include additional parameters.

Parameter Description
event One of: bounce, deferred, delivered, dropped, processed
email Email address of the intended recipient
smtp-id An id attached to the message by the originating system

Default Parameters for Engagement Events

The following parameters are sent with engagement events: click, open, spamreport, and unsubscribe events. Some events may include additional parameters.

Parameter Description
event One of: click, open, spamreport, unsubscribe
email Email address of the intended recipient
useragent The user agent responsible for the event, e.g. “Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.95 Safari/537.36”
ip The IP Address where the event originated

Unique Arguments and Categories

Events generated by SendGrid can also include unique arguments. To define and receive custom parameters in your URL the SMTP API must be used when sending emails using the unique_args argument. For example, if you have an application and want to receive custom parameters such as the userid and the email template, you would submit them in the SMTP API header or parameter, as described on the Unique Arguments documentation page, they would then be returned in the events like so:

1
2
3
4
5
6
7
8
9
10
[
  {
    "email": "john.doe@sendgrid.com",
    "timestamp": 1337966815,
    "event": "click",
    "url": "http://sendgrid.com"
    "userid": "1123",
    "template": "welcome"
  }
]

Categories

If categories are used over the SMTP API they will be returned by the Event Webhook as such:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[
  {
    "email": "john.doe@sendgrid.com",
    "timestamp": 1337966815,
    "category": [
      "newuser",
      "transactional"
    ],
    "event": "open"
  },
  {
    "email": "jane.doe@sendgrid.com",
    "timestamp": 1337966815,
    "category": "olduser"
    "event": "open"
  }
]
If you apply multiple categories to any of your outgoing messages, the returned data will be in the form of an array, if there’s only one category, however, it will be returned as a string.

Example

The following example uses PHP to store webhook requests in /tmp/dump.log:
1
2
3
4
5
6
7
8
9
10
11
<?php
$fh = fopen('/tmp/dump.log', 'a+');
if ( $fh )
{
// Dump body
fwrite($fh, print_r($HTTP_RAW_POST_DATA, true));
fclose($fh);
}

echo "ok";
?>

Parameter Details

The following shows each type of event that can be posted along with the specific parameters that go along with the event.

You can use the SMTP API to specify additional custom parameters including categories and unique args. Each unique arg is posted as a separate post parameter, similar to the category listed below, but with a custom name specified by you.

Processed

event email category
processed Message recipient The category you assigned

Deferred

event email response attempt category
deferred Message recipient Full response from MTA Delivery attempt # The category you assigned

Delivered

event email response category
delivered Message recipient Full response from MTA The category you assigned

Open

event email category
open Message recipient The category you assigned

Click

event email url category
click Message recipient URL Clicked The category you assigned

Bounce

event email status reason type category
bounce Message recipient Status code string, e.g. 5.5.0 Bounce reason from MTA Bounce/Blocked/Expired The category you assigned

Drop

event email reason category
dropped Message recipient Drop reason The category you assigned

Spam Report

event email category
spamreport Message recipient The category you assigned

Unsubscribe

event email category
unsubscribe Message recipient The category you assigned

Marketing Email Unsubscribes

For emails sent through our Marketing Email tool, unsubscribes look like the following example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[
    {
        "email": "nick@sendgrid.com",
        "timestamp": 1380822437,
        "newsletter": {
            "newsletter_user_list_id": "10557865",
            "newsletter_id": "1943530",
            "newsletter_send_id": "2308608"
        },
        "category": [
            "Tests",
            "Newsletter"
        ],
        "event": "unsubscribe"
    }
]

Troubleshooting

Ensure that your web server is returning a 200 response to our servers. Any other response type will result in our server retrying a POST until we receive a 200 response or the maximum time has expired. All events are retried at increasing intervals for up to 24 hours after the event occurs. 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.

You can use the “Test Your Integration” button on the Event Notifications settings page to send simulated events to your callback 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.

1
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":"http://sendgrid.com"},{"email":"john.doe@sendgrid.com","timestamp":1337969592,"smtp-id":"<20120525181309.C1A9B40405B3@Example-Mac.local>","event":"processed"}]'

Version Differences

The primary difference between v2 and v3 of the Event Webhook is Version 3 deliverers events as JSON arrays, whereas the previous version delivered batched JSON as JSON documents separated by line breaks. Further, v3 provides more data with certain events. The [previous version of the webhook’s documentation](http://sendgrid.com/docs/API_Reference/Webhooks/event_deprecated.html) is still provided so you may compare.