Using Lob Webhooks to Send Delivery Notifications in Rails

Traditionally, tracing mail is a difficult and time consuming process. However, recent tech innovations are changing the landscape. At Lob, most of our customers would like to keep track of their mail pieces in real time as they move through the USPS mail stream.

With Lob, you can now set up webhooks to receive real-time tracking events to show you exactly where your mail is in the delivery process. This tutorial will show you how to build a Rails web app that is ready to receive Lob’s webhooks.

Hate to read instructions? We’ve got all the source code for this example available in a public repository.

What are we building?

This tutorial will show you how to build a website to verify your personal address by sending a postcard with a unique verification code. Once you build the site and add an intake form, you can use Lob’s webhooks to set up automated emails as the postcard moves through transit and delivery.

Who is this tutorial for?

This tutorial is geared towards web developers that have at least some experience with Ruby on Rails. You don’t need to be an expert, but it will help to have played around with Rails and APIs before.

The Toolkit

  • Ruby on Rails – Rails is a popular web application framework running on the Ruby programming language.
  • Lob’s Postcard API – Lob has a whole suite of RESTful APIs for printing and mailing. We will be using the Postcard API in this tutorial.
  • Lob’s Webhook API – We’ll also be using Lob’s Webhook functionality.
  • SendGrid API – We’ll be using SendGrid’s Ruby Gem to send out email notifications.

Prerequisites

Before diving into the code, we will need to register for a Lob and SendGrid API key.

Lob

lob registration page

Visit the registration page and sign up for an account. You will be given a Test API Key which will give you full access to the API in a sandbox environment. All of Lob’s Printing APIs are free to try. When in Test mode, you can create postcards and view them in the dashboard, but nothing will actually be mailed until you use a Live API Key.

SendGrid

sendgrid registration page

Sign up for a SendGrid account and create an API Key.

Create the Project

Install Dependencies

Place all the Ruby gems we will be using to create our app in the Gemfile. The versions we will be using in this tutorial are as follows:

Set Up the User Model

We’re going to be using Devise, a popular, flexible authentication solution for Rails.

After this, we’ll create a User table and model by utilizing another one of Devise’s generators.

Now that we have Devise set up, we’ll need to add a few fields to the User table.

verification_code – store unique verification code that will be printed on the postcard
verified – store verified state
verification_postcard_id – store the id of the postcard returned by Lob’s API
first_name, last_name, … address_country – store postcard delivery address

/db/migrate/xxxxx_add_verification_to_user.rb

Now we can run the migrations.

In the model, you will see that Devise has added in some code to handle authentication automatically. We’ll use a before_create hook in the model to generate a unique code before saving the user to the database. To do this, we can use the SecureRandom library.

We’ll use an after_create hook to trigger a Sidekiq worker that will receive the user_id and send the verification postcard. We’ll be creating this worker later.

/models/user.rb

Create the Sign Up Page

We’ll need to modify the registrations controller and views created by Devise to accept these relevant fields upon sign up.

/controllers/registrations_controller.rb

/views/devise/registrations/new.html.erb

Generate Postcard Worker

Next, we’ll need to create the Sidekiq PostcardWorker we called in the User model earlier.

In our worker, we’re going to initialize the Lob client and lookup the user_id passed in, so we can determine the verification code we need to print on the postcard. We’re going to use the postcard template found in the lob-templates GitHub repository. We’ll pass in the first_name and verification_code as data parameters.

Once we successfully complete the request, we’ll store the postcard_id Lob returns so that we can associate which user should be receiving the tracking notifications.

/workers/postcard_worker.rb

Sanity Check

Let’s add a home page and some quick routing logic so we can see a preview of what we have so far. Running the command below, we’ll have a empty controller and view generated for us.

We’re going to mount Sidekiq’s web interface at /sidekiq and add some authentication logic. If a user is authenticated, they’ll be able to see the home page. If not, they’ll be directed to the registration form.

/config/routes.rb

Now if we start up Rails and Sidekiq…

We should get something like the image below. Signing up will now generate a user and trigger a postcard with a verification code.

lob webhooks demo sign up

Register the Webhook

Now we want to receive Webhooks that Lob sends us, so we’ll create a controller and Sidekiq worker to manage this. If you are writing this application in a development environment, we highly recommend using ngrok to test your webhooks. This way, you don’t have to continuously deploy your application to view any changes that you make.

Let’s add 2 additional routes, one to accept webhooks, /lob/webhooks and the other /verify to build a form to verify the unique code. We’ll set up the latter in a bit.

/config/routes.rb

Now let’s setup Webhooks in Lob’s dashboard. We’ll want to input the URL (whether it’s a deployed URL or one generated from ngrok) and select all of the postcard tracking events (postcard.in_transit, postcard.in_local_area, postcard.processed_for_delivery, postcard.re-routed, and postcard.returned_to_sender).

lob webhooks dashboard

We’ll read in the request body and parse the JSON returned by Lob. We’ll call the Sidekiq Worker, TrackingWorker, to send the actual email.

/controllers/webhooks_controller.rb

In the worker, we perform a user lookup so that we to whom we are sending the email. Then we trigger a call to SendGrid with the information provided in the webhook.

/workers/tracking_worker.rb

sendgrid email notification

Now we just need to verify that this is the correct verification code! Let’s go back to the HomeController we created earlier. We’ll add some simple logic to determine if the verification code entered is the same as the one we generated for the user.

/controllers/home_controller.rb

And a really simple view.

/views/home/index.html.erb

lob verify your address

Wrapping Up

Now you have a fully functional address verification system using Lob’s postcard and webhook functionality!

You can see the full source code for this example here.

You can check out Lob’s documentation and webhooks guide for more information. If you have any additional questions, don’t hesitate to leave a comment below or contact us directly. We’re always happy to help!