Ingesting tracking events with webhooks
Ingesting tracking events from Lob has been made easy. With List endpoints, GET endpoints, and webhooks, you can ingest events for a specific mail piece, run a monthly data pull from Lob's system for mail pieces that don't have a certain event, or get real-time updates as your mail piece goes through the mail stream.
Why is this important?
Ingesting tracking events from Lob can unlock a slew of functionality for an organization. By ingesting this data from Lob, you can integrate direct mail into your omni-channel workflows, surface data internally for reporting purposes, provide updates to customers to improve their customer experience, and much more.
If someone needs to monitor tracking events in near real-time, and subsequently build additional triggers off of those events, then they have to take a few more steps during integration. That includes setting up an API endpoint for Lob to send data to, as well as developing the logic that each event should follow in their internal systems. For example, “processed for delivery” events could trigger an email to be sent.
How do we (programmatically) solve this problem?
First, you need to understand the model by which you want to receive or fetch this data. If you desire to receive data in real time, then you will need to set up a webhook endpoint for Lob to send data to. You can subscribe to a list of events in the Lob dashboard and then build on top of these events inside of your application. keep in mind, customers should have systems in place that, in the event their endpoint goes down, that will enable them to backfill the data they need. If they need to retrieve tracking events on-demand, then having the systems in place to do so is imperative.
For the fetch model, systems can be put into place to programmatically retrieve mail pieces details, either in batches or per resource, and extract their most up-to-date tracking data. To do this, you can either use our GET endpoints to retrieve all of the current information for a specific mail piece, or you can use our LIST endpoint to retrieve multiple letters at once based on the desired filtering such as metadata filters, date filters, etc. This model can be used in many ways to help enable your business, but most commonly these are run on a daily/weekly cadence, or they are run ad hoc when the webhook ingestion process has failed to ingest the data.
Setting up an endpoint to receive data from Lob
In this guide, we’ll share the steps and code you’ll need to stand up an endpoint to receive data from Lob. The code is designed to run on your local machine in order to test out receiving webhooks from Lob during development. In order for Lob to reach the endpoint you’ll use ngrok, a cross-platform application that exposes local server ports to the Internet.
To follow along with this guide, you will need:
ngrok installed on your laptop
A webhook configured in your Lob.com account (we’ll show you how below)
Set up a new project
Let’s start by creating a folder for our project and installing any libraries.
Create a new directory, switch to it, and initialize your project from your terminal app with these commands.
For this example, we’ll use KOA an HTTP middleware framework for node.js along with supporting libraries.
Create two directories to hold our typescript file and our compiled javascript file.
We’re also going to add nodejs-specific type definitions as a dev dependency. Otherwise, the TS compiler would complain about some globally available objects that it doesn’t know about.
Let's configure how the compiler works in the project by creating a new file called tsconfig.json and setting some values.
Lastly, we’ll update package.json so main equals “/dist/index.js”
Creating a webhook endpoint
Now all our dependencies are installed on your local machine, we’ll add the code for our endpoint.
Open the text editor of your choice (if you need to download one, we recommend Visual Studio Code) and paste the code in the language of your choice.
Open index.ts and copy and paste the following code.
Return to your terminal and from the project folder run your code.
Launch ngrok
As mentioned, we’ll use ngrok to expose your webhook endpoint to the internet.
In another terminal window, navigate to the folder where you installed ngrok and run the command
You’ll see a forwarding URL for https connections. You’ll copy this for use when configuring your webhook in Lob in the next section.
Configure your webhook in Lob
Login to your Lob.com account from the dashboard
Click on Webhooks on the left side navigation.
Click the Create button
Give your webhook a description
Check the boxes for all the events you want to receive notifications.
Paste the ngrok forward URL and append “/webhooks” for your endpoint. Example: https://03ed-67-170-227-250.ngrok.io/webhooks
Click the Create button
Test using the debugger
After successfully creating your webhook in Lob, click the Debugger button. Then click the Send button. You should see a 200 OK message in the webhook response window.
Further resources
More about Webhooks for tracking events
Last updated
