Event

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. A common use of this data is to collect information about how specific mail campaigns or categories of mailings are progressing. Using Unique Arguments and Category parameters, you can insert dynamic data that will help build a sharp, clear image of your mailings.

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

Setup

To setup the Event Webhook, 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.

If you’d like to receive batched events, check the “Batch event notifications” checkbox to enable the feature, then click the save button. This will not, however, turn on the function. To do that, return to the Apps page and click on enable on the Event Notification app.

Info 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

Warning If you wish to receive encrypted posts, we require that your callback URL support SSL v2.

Requests

You have the option to receive a HTTP POST request for each event or to receive a batch 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.

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. This means that if you use batched events these events will drop due to 24 hours before the queue can max out. Events that cannot be submitted within the maximum retry period or events removed from the defer queue will be lost.

Warning If your email traffic generates lots of events, the incoming amount of data can easily overload a web server if not configured properly for scalability. To reduce the number of requests to your server, enable the batched events option.

Keep in mind that even with batched events enabled, your servers can potentially see a large number of POSTs from the webhook as we POST batches from multiple servers. You can load test your endpoints with loader.io for free.

Event Types

The following lists the events generated by SendGrid.

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

Parameters

The following is a list of parameters that are always passed with each event. Some events include additional parameters. Also a category name and custom argument may be passed. Please see the Custom Parameters and Categories section below for more information.

Custom Parameters and Categories

Events generated by SendGrid can also include custom parameters. 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 user id and the email template name, include the following in your SMTP headers as X-SMTPAPI or as the xsmtpapi parameter of your Web API call:

1
2
3
4
5
6

{
  "unique_args": {
    "userid": "1123",
    "template": "welcome"
  }
}

Either of those emails will generate the following HTTP POST request to your application when the email is opened:

1

email=emailrecipient@domain.com&event=open&userid=1123&template=welcome

Categories

If a category is used over the SMTP API to get detailed statistics for user signups in addition to custom parameter, include the following in your SMTP headers as X-SMTPAPI or as the xsmtpapi parameter of your Web API call:

1
2
3
4
5
6
7

{
  "unique_args": {
    "userid": "1123",
    "template": "welcome"
  },
  "category": "user_signup"
}

Either of those emails will generate the following HTTP POST request to your application when the email is opened:

1

email=emailrecipient@domain.com&event=open&userid=1123&template=welcome&category=user_signup

Info If you apply multiple categories to any of your outgoing messages, the returned data will be in the form of an array.

Batched Events

Batched event POSTs have a content-type header of application/json, and contain exactly one JSON string per line, with each line representing one event. Please note that currently the POST headers define this post as application/json, though it’s not; each line is a valid JSON string, but the overall POST body is not. For example:

1
2

{"email":"foo@bar.com","timestamp":1322000095,"unique_arg":"my unique arg","event":"delivered"}
{"email":"foo@bar.com","timestamp":1322000096,"unique_arg":"my unique arg","event":"open"}

Info Batched events currently post every 1 second, or when the batch size reaches 1MB (one megabyte), whichever occurs first.

Info Batching your events is recommended to reduce server load and reduce the number of open connections.

Examples

1
2
3
4
5
6
7
8
9

<?php
$fh = fopen('/tmp/dump.log', 'a+');
if ( $fh )
{
// Dump body
fwrite($fh, print_r($HTTP_RAW_POST_DATA, true));
fclose($fh);
}
?> ok

1
2
3
4
5
6
7
8
9

<?php
$fh = fopen('/tmp/dump.log', 'a+');
if ( $fh )
{
// Dump parameters
fwrite($fh, print_r($_POST, true));
fclose($fh);
}
?> ok

Info If you are using a hosting service, you don’t have direct access to the server’s file system. In that case, you need to modify the path for the dump log to be somewhere you do have access to. In most cases, the second line in the code above…

1
2
3

<?php
$fh = fopen('/tmp/dump.log', 'a+');
?>

1
2
3

<?php
$fh = fopen('~/dump.log', 'a+');
?>

Parameter Details

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

Info 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

Deferred

Delivered

Open

Click

Bounce

Drop

Spam Report

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 three days 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. Also, you can try a test POST yourself from a terminal by running the following command. This will give you the full response your server is returning including the HTTP headers.

1

curl -i -d 'email=test@gmail.com&arg2=2&arg1=1&category=testing&event=processed'