Notifications – Webhooks

Complexity:    

Audience: Management Team, Developers, Loan Servicing/Collections Managers, Administrator, Data

Introduction

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

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.

Available Events
  • 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

Trigger-Based Notifications

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:

Configuring Webhooks

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.

Callback URLs and Tokens

Next, you can determine some of the finer details. Enter the URL you want to call into the 'Callback URL' field. If you would like to use authorization tokens for your webhook, you can set the token yourself or generate a random one. Tokens ensure greater security from DDoS attacks and allow you to protect yourself from unwanted webhook requests.

If you plan on using tokens, make sure to whitelist the IP addresses that LoanPro sends webhooks from. These IP addresses can be viewed by clicking the 'Source IPs' button on the right side of the page.

Retries

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.

Configurable webhook retry settings are a new feature, and you may have existing webhooks that will now be affected by the update. Your existing webhooks will now default to three retries (like they did in the past), but you can update these settings if you'd like.

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.

When a webhook notification is retried, the variable information in the payload will exactly match what would have been sent with the first attempt. Even if information has been updated in LMS, the webhook information will remain the same.

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.

Restrictions

Next, you can set restrictions that will specify the loans for which notifications will be sent.

Restrictions give you 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.

Payload Variables

Lastly, enter the variables that will be sent as part of the webhook notification when the event occurs. Click the 'Help Variables' button to view a list of the available variables. 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'. 

Here's a sample JSON payload from a webhook:

This is an example of what a webhook payload may look like.

{
"eventName": "Account Activated",
"context": {
"loan-display-id": "727",
"agent-full-name": "",
"source-company": "Two Birds, One Loan",
"status-stoplight": false,
"loan-create-time": "",
"status-days-past-due": 13,
"last-payment-amount": 0
}
}

Terminology

Here are some common terms that are used when discussing webhooks:

Term

Definition

event

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.

trigger

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.

webhook/callback URL

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.

payload

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.

retries

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

Timeouts tell a webhook to give up on its request if it hasn't received a response after a specified amount of time.

trace ID

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.

What's Next

Now that you have set up your own webhooks, you may want to some visibility for 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 as well as manually resend them. To learn how to manually resend webhooks, take a look at our Webhooks at the Loan Level article.


How did we do?


Powered by HelpDocs (opens in a new tab)