Webhooks

Webhooks are an easy way to get notifications on events happening asynchronously within Lob's architecture. Some common use cases for integrating webhooks are:

  • Sending end users notifications about mail traveling through the postal stream
  • Receiving notifications about erroneous scan events, such as "Re-Routed" or "Returned to Sender"
  • Downloading PDF previews or thumbnails automatically once they are rendered
  • Internal logging and reconciliation

When an event occurs within our architecture and you have a webhook subscribed to that event type in that Environment (Test vs. Live), we will attempt to make a POST request with the entire event object to the URL provided. See here for a full list of all available event types that you can subscribe to.

NOTE: In Live mode, you can only have as many non-deleted webhooks as allotted in your current Print & Mail Edition. There is no limit in Test mode.

Receiving a Webhook

To receive webhooks from Lob, you just need to create another endpoint on your web server that will accept a POST request with a content type of application/json. Keep in mind that it will need to be accessible by us so if there's anything that could prevent Lob from accessing it should be disabled for this endpoint. However, we do have recommendations on how to secure your endpoint.

To confirm delivery of the webhook, Lob expects a 2xx status code returned in a timely manner. We will consider any other status code (or lack of status code) to be erroneous and attempt to retry the delivery. If your webhook endpoint has any additional complex logic to perform, we recommend immediately returning a 2xx to let us know that you don't want to receive this event again, and then performing that logic afterwards. This should aid in preventing unwanted retry attempts caused by unexpected network timeouts.

Any other information sent back to Lob in the response will be captured and stored (regardless of status code) for you to view on your Dashboard, though we won't perform any processing on it. Therefore, we recommend responding with any information that you may find useful for debugging purposes. While you can return anything (including HTML), we've found it most helpful to return a concise JSON object with anything that could be relevant.

Test vs. Live Environment

Events are created in both your Test and Live Environment, and Webhooks can also be created in both. Please note that Webhooks created in the Test Environment will be triggered off events from your Test API Key, while Webhooks created in the Live Environment will be triggered off events from your Live API Key.

Because tracking events only ever exist in Live, these event types can not be subscribed to in the Test Environment. To debug, you can "fake" the sending of these events to your server by using our Debugger.

Integration Tips

When first starting out, we recommend using our Debugger. This tool allows you to trigger a generated event body to your specified URL on command. This should mainly be used to determine JSON structure when integrating. Since the event bodies sent are fake, all IDs and URLs within them are not accessible and do not map to real resources in your account.

Once you've started local development of the web server that will be handling these requests, we recommend using a tool that provides local tunneling, such as ngrok. This allows you to expose your locally running server to the Internet so we can access it without you needing to deploy your application.

Retry Policy

When webhook attempts executed by Lob do not succeed (e.g. do not receive a 2xx status code, hit a SSL/TLS error, DNS issue, etc), we will continue to try to deliver the same event according to a schedule with an increasing back off. This policy is meant to give you time to rectify the issue without losing any events.

We will attempt the webhook at the following intervals until we either receive a 2xx status code or all 8 attempts have been executed:

Attempt # Time since last attempt Time since first attempt Example
1 n/a 0 min 2016-01-01T00:00:00Z
2 1 min 1 min 2016-01-01T00:01:00Z
3 5 min 6 min 2016-01-01T00:06:00Z
4 30 min 36 min 2016-01-01T00:36:00Z
5 1 hr 1 hr 36 min 2016-01-01T01:36:00Z
6 6 hr 7 hr 36 min 2016-01-01T07:36:00Z
7 12 hr 19 hr 36 min 2016-01-01T19:36:00Z
8 24 hr 43 hr 36 min 2016-01-02T19:36:00Z

This means that if a webhook attempt continuously fails, Lob will stop attempting webhook requests 43 hr & 36 min (approximately 1.82 days) after the initial creation of the event.

Capacity

It's important to note that for every API request you send to Lob, you may get multiple requests back to your server, depending on what event types you have subscribed to. For best results, please make sure your servers will be able to handle the load you expect to get back.

Security

We understand that security is an important concern when granting external access. You need to make sure that Lob is able to access your endpoint, but you don't want anybody being able to access it or your data, so there are certain features that you can enable on your end to ensure this is possible.

TLS

We enforce HTTPS for all webhook URLs. Securing your endpoint with TLS ensures all data being sent to and from your server is encrypted. Make sure that you're using a fully-chained certificate, or else the request will never make it to your server and the attempt will fail. To make sure they are fully-chained, you should use the Debugger and see if the request successfully goes through.

Basic Authentication

While we don't require it, we highly suggest adding Basic Authentication to guard your endpoint from public access. When creating your webhook, just append the username and password to the URL using the following format: https://username:password@example.com/webhooks. This will be converted on our end to the appropriate Authorization header when we make the request. It is recommended to use authentication in conjunction with SSL/TLS so that your credentials will be encrypted.

CSRF

A common feature that is enabled by default for some frameworks is cross-site request forgery. This is an valuable security measure to ensure that authenticated users aren't performing actions that aren't intended. However, having it enabled on your webhook endpoint could prevent our events from being processed. Instead of disabling it completely, you should just exempt this endpoint from CSRF validation.

API Versions

We will always send events based on the API Version on your account at the time of event creation. If your account is set to an older API version but a request is sent with a hard coded header, the Event generated will still be based on the API Version on your account at that time. Event objects in the past will not be updated if you upgrade your API Version - only subsequent events will follow the new Version's structure.