Tutorial: Event Notification App (Event Webhook)
Time to read: 4 minutes
Our VidGrid Tutorial for today is focused on one of our more popular webhooks - the Event Notification App. Our Event Webhook allows you to monitor all activity through your SendGrid account in real-time. Tom goes into detail on how to set this up using the app in your account and adding the necessary files to your host server.
The Event Notification App is a great tool offered by SendGrid to allow real-time monitoring of all your email activity through your SendGrid account without the limitations of the Email Activity page. The Event Notification App is offered to our Silver and higher customers. You can access the Event Notification App by going to your Apps page and selecting Event Notification.
If you don’t have this feature enabled, you’ll want to go to Show Disabled Apps and then you will see the Event Notification icon display. You can access the settings of the Event Notification App by simply waving your mouse over the icon, and click on Settings.
The Event Notification App allows the user to create an endpoint where SendGrid can make an HTTP post of all your email activity. You can set what kind of events you want to be posted based on the things that you have under your Event Notification App. What an end point is, is essentially creating a whiteboard for SendGrid to send information to. This information will come in the form of a JSON string. Whenever a certain event occurs, SendGrid will write, or in this case post, this event to your endpoint. And within this application you’ll be able to see all the settings that you can enable within the Event Notification App. Events that you can get from the Event Notification App are:
Emails marked as spam
At the bottom of the screen, within the Event Notification settings, you also have to option to batch events. In order to make use of the event Notification App, you need three things:
The correct package level, which is silver or higher package level.
You will need a hosting server such as GoDaddy, Rackspace, Host Gator, or other hosting service providers.
You will need some coding or programming background. In this case, for the example that I’m going to use, I will use PHP which can be found in our documentation page.
If you choose to use the PHP code provided on our documentation page and set up the Event Notification App within your SendGrid account your end product will look like this. Here we have a list of all the email activity that happened in my account as a JSON string, but also as a batched event. The difference between a batched event and a non-batched event is that with the non-batched event Sendgrid will post every time there is an event occurring within your account. The batched event will post every second, or when the batch size reaches the 1 megabyte limit.
So how do you know when to use the non-batched events versus the batched events? This will depend on how much incoming information your hosting server can handle. If you don’t have a large amount of email activity being sent to your endpoint or whiteboard from SendGrid, then the non-batched option will be fine. For those experiencing a large number of email events you’ll most likely want to use the batched option because this will reduce the amount of load on your endpoint server.
documentation. To access the PHP example you’ll want to go to the documentation homepage at docs.sendgrid.com. Click on API Reference, Webhooks, and lastly Event. On this new page, you’ll want to scroll down to the section called Example. In this example you have two different types of PHP code to use. You have the batched event which we explained earlier, and we have the non-batched event.
Creating a PHP File
In this example, I decided to use the batched event for my PHP code. So, to create a PHP file you’ll want to open Notepad if you’re using the Windows operating system or TextEdit if you’re using a Mac operating system. In my example I’m using a Mac operating system. With the Mac operating system I open my application called TextEdit, and I will copy the PHP code and paste it into the new application that I opened. Keep note though, I want to change the location of this file where I want the dump.log file to be placed. I would like this placed in my root domain, so add the tilde symbol (~), forward slash (/) dump.log (´~/dump.log.) You’ll want to save the file as a .php example.
Once I’ve created the PHP file, I want to upload this to my hosting server. Here, within my hosting server you can see that I’ve already uploaded the eventapi.php file that I recently created. Once the file is uploaded you’ll want to point to this file in your Event Notification App settings within your SendGrid account. After you’ve made the appropriate changes, you’ll want to click on Save Changes to make sure that everything is saved, and be sure to select Enable for the Event Notification App. Once this is done you can go to the domain location of the file. Within this page you’ll be able to see all the email activity happening through your SendGrid account.