Notifications – Webhooks
- How Webhooks Work
Audience: Management Team, Developers, Loan Servicing/Collections Managers, Administrator, Data
If you're a lender that has their own custom application—or uses systems in addition to LoanPro to operate your lending—you likely need a way to receive notifications when loan events occur or specific loan conditions are met. If this applies to you, webhooks are a great tool to use. As we discuss in our Webhooks 101 article, webhooks make it possible to send information to specified URLs. If you're new to webhooks, building out integrations can sound complicated. LoanPro's built-in notification tools eliminate the complexity entirely; our tools allow any user to easily configure webhooks to work in tandem with their custom application.
In this article, we'll explain how to create your own webhooks and the available configuration options.
How Webhooks Work
LoanPro's implementation of webhooks features an array of configuration options. Like other notification methods, webhook configurations allow users to send webhooks based on two different categories of criteria: events and triggers. We'll touch on the differences between these two categories, but configuring webhooks for each category is similar—only the beginning step of determining your criteria differs between the two. If you're familiar with the categories, feel free to skip to Configuring Webhooks.
Event-based webhooks allow you to send information every time a LoanPro event occurs. This type of webhook is most commonly used to notify other applications (even applications built by you, if needed) when events occur in LoanPro. To see a full list of available webhook events, feel free to expand the following fold.
- Insurance Updated
- Autopay Failed
- Autopay Scheduled/Created
- Loan Settings Updated
- Loan Promise Created
- Loan Collateral Updated
- Document attached to Account
- New (API) Token Issued
- Advancement Posted to Account
- Credit Posted to Account
- Past Due Adjustment Posted to Account
- Change Due Date Posted to Account
- Funding Transaction Posted to Account
- Payment Posted to account
- Payment Reversed
- Loan Charge Posted
- Loan Charge Reversed
- Archive Account
- Delete Account
- Account Created
- Account Modified
- Account Activated
- Customer Logs into Customer Website
- Customer Website Document Upload
- Customer Created
- Customer Updated
- Payment Profile Added
- Employer Updated
- References Added
- Agent User Created
- Daily Maintenance - Queued
- Daily Maintenance - In Progress
- Import Updated
- Import Validated
- Import Ingested
- Import Verified
- Import Completed
- Custom Loan Status Change
- Custom Portfolio Change
Event-Based Webhooks also allow you to use restrictions for a more granular level of control. Selecting values for any of these options will restrict notifications to ensure they're only sent for loans that fall within the value's parameters. You can also set Portfolio restrictions which will only include loans within selected portfolios.
Trigger-based notifications differ from their event-based counterparts. These notifications are based on customizable, user-determined triggers that are written with Clojure. Triggers provide a much finer level of customization; however, they may seem a bit more intimidating if you're not comfortable writing Clojure statements. Here is an example of how to use the rule editor to create a trigger:
As a demonstration, we'll set up an event-based webhook. To set up an event-based webhook, navigate to Settings > Company > Notifications > Event-Based Notifications. Here, you can create, edit, and activate notifications. To create a new notification, click the 'Add' button in the top right corner.
After clicking 'Add', navigate to the webhook tab. You are presented with a few options on this page. Start by determining a name and description for your webhook notification. Then, select which event should prompt the webhook. And if you'd like to set up some more specific parameters, add some Restrictions for the webhook as well. These are listed a bit further down the page.
Method and Callback URL
Next, you can determine some of the finer details. Enter the URL you want to call into the 'Callback URL' field. This is the URL that you tell your webhook to send information to. This field can even include LoanPro's context engine variables, and here's an example of what that may look like:
When the webhook is sent, the loan ID variable will be replaced by the ID of the loan that fit the criteria for the webhook.
You'll also need to select the method for the webhook. Like when using LoanPro's API, you can select between four method types: GET, PUT, POST, and DELETE. Of those options, GETs, PUTs, and DELETEs are a webhook feature that incur costs.
Authorization Tokens and Custom Headers
Next, you'll determine if you'd like your webhook to be authenticated. This is optional, but authentication requirements will depend on where you plan on sending your webhook. There are a few authentication options available here, so let's discuss when you may want to use each option.
Tokens provide greater security from DDoS attacks and allow you to protect yourself from unwanted webhook requests. We recommend using tokens with your webhooks as an added layer of defense and security. If the URL you're sending a LoanPro webhook to uses a simple authentication token, paste the token into the 'Authorization Token' field. If desired, you can also generate a new token here and copy it to the receiving system.
The Custom Headers section offers a bit more customization. Here, you can list the header parameters that a receiving system uses. This is useful if you're sending your webhook to an API, as most APIs use more than one authorization field to authenticate requests. For example, the LoanPro API authenticates requests with the following set of headers:
If you'd like to send your webhook to the LoanPro API, you'll need to add those headers listed above in the 'Custom Headers' section. To do so, simply click the 'Add Header' button to add a new header field. The webhooks feature will allow up to 25 fields here. Using Custom Headers is a webhook feature that incurs costs.
Next, set the webhook retry settings. Retries are sent when a webhook fails, which is defined as receiving a response code between 200-299. In addition, a retry will be attempted if LoanPro does not receive any response at all after 45 seconds. You can set up to 50 retry attempts, and you can determine how much time the system will wait between sending the next request. Alternatively, you can set your webhook to send no retry attempts at all.
Each webhook response will include a trace ID. This is in the payload for logging purposes, allowing LoanPro to see which of the retries succeeded, and will have no effect on your processes.
Webhooks can also be manually retried, but only at the loan level. To learn how to manually retry webhooks, take a look at our Webhooks at the Loan Level article.
Lastly, you'll want to enter the variables that will be sent as part of the webhook notification when the event occurs. You'll notice that there are two text boxes here. The first section allows you to select which LoanPro variables to include in the webhook. To view and add variables, click the 'Help Variables' button. You will only need to enter the variable names (e.g. status-amount-due), and you will need to separate listed variables by commas like shown below. When you are done, click 'Save'.
When the webhook is sent, the variables here will be sent in a JSON format.
Here's a sample JSON payload from a webhook:
This is an example of what a webhook payload may look like.
"eventName": "Account Activated",
"source-company": "Two Birds, One Loan",
The 'Custom Body Formatting' section allows you to send the payload in any format you'd like. This is a webhook feature that incurs costs, but it's useful if you'd like to use a webhook to send a specific payload to an API:
Once you've added information to all sections of the webhooks page, simply hit 'Save' to add your webhook.
Here are some common terms that are used when discussing webhooks:
In the context of webhooks in LMS, an event is a change that is made to a loan. LMS provides event-based webhooks as a form of change criteria. Examples of events are loan status changes, payments, modifications, etc.
In the context of webhooks in LMS, a trigger is a custom-made criteria that looks for a change made to a loan. Trigger-based notifications allow users to set Clojure formulas for flexible and customizable criteria.
This is the URL that you tell your webhook to send information to in the form of a payload. LMS provides a way for users to set this within the UI.
This determines what the system does with the information in the webhook. Different methods do different things:
A payload is set of text that a webhook generates when you receive a response. This holds the information that your request asked for. Similar to responses you would receive from sending a request to our API, they are typically in a JSON format.
When a webhook receives a failure response, it is retried after a specified amount of time. We go into more detail about this topic in our Notifications – Webhooks article.
Timeouts tell a webhook to give up on its request if it hasn't received a response after a specified amount of time.
Identification information included in in the webhook payload for logging purposes. The trace ID allows LoanPro to identify which of the retries succeeded, and it has no effect on your webhooks. This ID remains the same even if the webhook is retried multiple times.
Now that you have set up your own webhooks, you may want some visibility over which webhooks are successful. Webhook history is viewable within the Reports tab, and our Webhooks Report article explains the topic.
You can also see which webhooks were sent for any individual loan and manually resend them. To learn how to manually resend webhooks, take a look at our Webhooks at the Loan Level article.
Lastly, if you'd like a more in-depth look at the capabilities of our webhooks feature—including some use case examples of how to configure some automations—take a look at our Webhooks – Advanced article.