Integration Overview

Klaviyo is a popular marketing automation software tool. It frequently uses integrations like Shopify to external systems like Lob. In early 2022, Klaviyo added webhook functionality, enabling a direct connection to Lob (prior to this, data had to be extracted from Klaviyo and passed to Lob via a separate system). Klaviyo’s webhook functionality within their flows interface provides an easy connection point to trigger automated, personalized Direct Mail with Lob.

Getting started

We’ll assume you have a Klaviyo account and you have already registered with Lob (for your API Keys and the like) to follow along.

In order to send mail from Klaviyo, Lob requires a mailing address to be stored for each profile. Klaviyo does not require mailing addresses by default, so before attempting to send mail, ensure that your recipient profiles contain properties for:

• Address
• City
• State
• Zip Code

If you are importing new profiles to Klaviyo, simply ensure that you have CSV columns for each of those properties. An example CSV to import Profiles is linked here.

Creating a Flow

In the Klaviyo dashboard’s left-hand panel, click on Flows. Then click to Create Flow, then select a predefined goal, or click Create From Scratch and give your flow a name. Then choose a Trigger Setup option in the left panel. For this example, we will be selecting List, and choosing a list from the resulting drop-down to trigger the flow (we selected Newsletter).

 

Creating a Webhook

Once you have configured your trigger, an Actions menu will appear on the left panel. Select Webhook, and drag it into your flow beneath the trigger.

Select the Webhook in your Flow, and the configuration panel will appear on the left side. You can configure it as follows:

Destination URL: This is where you will enter the Lob API URL for the form factor you would like to trigger. Example: https://api.lob.com/v1/postcards. Note that Lob has separate endpoints for postcards, letters, checks, self-mailers, etc. 

Headers: This is where you will enter the headers Lob requires in order to correctly process and authenticate the incoming requests. You will be required to enter at least two headers: Content-Type and Authorization. Click Add Header.

For the Content-Type header, enter the following:

• Key: Content-Type 
• Value: application/json

For the Authorization header, you will need your API keys.

Add Your API Keys

You can find your API keys in your Lob Dashboard under Settings, then click API Keys tab. 

For the Authorization header, you will need to have your Base64-encoded Lob API key ready to enter, so Lob can associate the request with your account. You can use a Base64 Encoder tool to encode it. 

For example, if your API key was test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc, you would enter test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: into a Base64 Encoder tool, the result of which would be something like dGVzdF8wZGM4ZDUxZTBhY2ZmY2IxODgwZTBmMTljNzliMmY1YjBjYzo=. 

Note that we added a colon (:) to the end of the API key before encoding it, you are recommended to do the same.

Once you’ve encoded your API key, add the Authorization Header and use the encoded key as the value. For example:

• Key: Authorization 
• Value: Basic dGVzdF8wZGM4ZDUxZTBhY2ZmY2IxODgwZTBmMTljNzliMmY1YjBjYzo=

JSON body

This is where you will pass Lob the information that informs the mailpiece. The field names (name, address_line1, etc). represent the information that Lob’s API will require. The values on the right represent what you will pass to Lob to populate the given field. 

The values can be mapped to attributes from Klaviyo profiles by using Klaviyo’s Profile variables. You can find the Profile variables for each attribute by taking the following steps:

 

An example of a populated JSON body could look something like the following. You can find more information on each of these fields in our API documentation. 

Update Creative

You will want to replace the values being passed for ‘front’ and ‘back’ with your own Lob template IDs or linked creative. For example:

"front": “https://s3.us-west-2.amazonaws.com/public.lob.com/lobcom/template_gallery/gtmpl_524eb6ff6c6998_Increase_Customer_Loyalty_Postcard_4x6_front.html"

"back": "https://s3.us-west-2.amazonaws.com/public.lob.com/lobcom/template_gallery/gtmpl_524eb6ff6c6998_Increase_Customer_Loyalty_Postcard_4x6_back.html"

(For more about designing/formatting creative for Lob, go here.)

Testing

You can test that your webhook is configured correctly by clicking on Preview Webhook. 

The resulting panel will show an example of the data being passed to Lob for a specific Profile. You can look at the JSON to verify that the Klaviyo Profile Variables are being correctly replaced. 

For example, instead of {{ person|lookup:'$address1'|default:'' }} you will see an address, such as ‘185 Berry St.’

If this all looks correct, double-check that you used your Test API Key (rather than your live one), then click on Send Test Request. If it was configured correctly, you will see the message: "Successfully sent Webhook."

 

You can then log into your Lob account to verify that your postcard was generated. (The below is the result of the example creative.)

Go time!

You will need to add payment information to your Lob account should you actually wish to print and send mailpieces. When you are ready, you can replace your Test API key with your Live API key; if you have your LIVE API key in the template it will create mail. If you are using other test resources like address IDs or template IDs, those will also need to be transferred to your live environment.

When you are testing make sure that your cancellation windows are set to an ample time (2 hours is recommended) so you can cancel mail if you make a mistake.

Troubleshooting common errors

1. 401 Unauthorized
   • If you receive this error message, your API key is incorrect. 
   • Make sure you have the header Authorization and that you are encoding your secret API key as explained above
      
2. 422 Unprocessable Entity (Invalid request payload JSON format)
   • If you receive this error, it is likely that your payload is not formatted correctly. It needs to match JSON formatting. 
   • Generally speaking, the rules that are often broken are:
     1. All keys and values are enclosed in double quotes (").
     2. Commas after every key-value pair except for the last one. 
     3. No newline characters in any values and no extra spaces between fields.
         
3. 422 Unprocessable Entity (Other)
   • Other than JSON errors, you can receive 422 errors in the payload sent to Lob does not match our requirements. 
   • For example, if you are missing address_line1 in the payload you will get an error saying that is needed. For these errors, you can make the appropriate adjustments and retry your requests.