The EasyPost Tracking API makes it simple to get EasyPost tracking updates with webhooks. Your application can be notified and take action as a tracking update happens. In this tutorial, we'll create a Sinatra application with the EasyPost Ruby Client that can receive webhooks from EasyPost. Then, we'll use the SendGrid API to send an email to a test customer after a package gets delivered.
Although we'll use Sinatra (and Ruby) in this example application, this functionality could be integrated into any app written with Ruby, PHP, Java, and other languages with EasyPost's official client libraries.
We'll start out by creating a
Gemfile with the dependencies we will need. This will be a new file titled
Gemfile in the project root directory. We can get away with a pretty minimal list, so let's add in the
sendgrid gems to communicate with the respective APIs, the
sinatra gem for our web application, and the
dotenv gem to load our configuration values in. Your
Gemfile should look like this:
At this point, we can go ahead and install our dependencies by running
bundle install, so let's do that.
Next, we can start writing our web application. Create a file called
app.rb and save it in the project root directory. Here are the first few lines:
In these first couple of lines, we import the dependencies we installed, the app is defined (we're using Sinatra's modular style) and the config variables are loaded. We then instantiate the EasyPost and SendGrid clients with the keys from our
Now comes the meat of the application. Let us add the post method to the
class App in
We know from the Webhooks Guide that incoming webhooks are POST requests, so we route
/easypost-webhook with the POST method. We also know from the Tracking API that webhooks for tracked packages come in an Event object, so we create one with the EasyPost Ruby client.
Next, we compose a message to be sent to the customer. In this example, we have some logic dependent on the status of the shipment, and create a message which includes the most recent tracking information. Because the order of tracking details can vary, we iterate through the list of tracking details until we find one that matches the status of the Tracker.
Lastly, we send an Email using SendGrid with the message that we just generated.
It's time to get the app started and see if we can get an email notification!
Open your shell, and run
bundle install and then run
$ ruby app.rb. The app is now running on port 4567, but there's one problem - since it's running locally, EasyPost has no way to access it! In a production application, our app would be running on a remote server, but there's no need to set one up for this example. Instead, we use a tool called
ngrok that can temporarily tunnel our app to the outside world.
Visit the ngrok website to install ngrok on your computer, then open a new shell. Simply run
$ ngrok http 4567, and ngrok will take care of all of the heavy lifting. You should see a URL that looks something like
https://something.ngrok.io in ngrok's output – copy it.
All that's left is to tell EasyPost where to send our webhooks. You can do this from the webhooks page, or by running the following cURL command (replace xxxxxxxx.ngrok.io with your ngrok URL and insert your actual EasyPost test API key):
It's time to see the results of our hard work! EasyPost will send us a webhook after we create a test Tracker. We use a test tracking code,
EZ2000000002 (you can find the full list of test tracking codes here):
In a few minutes, you should get a customized Email when an update occurs on the test Tracker:
Awesome! If you're interested, try playing with message customization using attributes listed in the Tracking API.