Webhooks 101

Complexity:    

Audience: Loan Servicer or Collector, Upper Management, Developers, Loan Servicing/Collections Managers, Administrator, Data

Introduction

In this article, we explain webhooks in basic terms. This is the article for those who have no experience with webhooks or are totally new to the concept. If you're familiar with webhooks and would like to skip ahead to learning how to set them up yourself, take a look at our Notifications – Webhooks article.

What is a Webhook?

Webhooks are connections between two programs over the web. One program sends specific information and the other has a place where the information can be received. They are used to send real-time information in the event of a change made in one of the systems.

How Webhooks Work

As we mentioned, webhooks connect two programs to create an alert when a change of some sort is made. They usually consist of two parts: a webhook notification and a webhook URL or callback URL. One program will provide the webhook notification, which consists of data that gets sent. The other program provides a webhook URL, the web location the webhook notification is sent to.

The webhook notification is typically sent when an event occurs. The program sending the notification determines what event will trigger the webhook. The webhook is sent to the webhook URL, where the program that is receiving the notification decides what to do about the data received.

The process makes a bit more sense with the use of an analogy. Setting up a webhook is sort of like setting up your own personal FBI surveillance team that's constantly keeping an eye out for activity over the internet. You tell the team to look for a specific thing, and when they see it, they call you immediately to relay you the information. Then, when you receive the information, you decide what you'd like to do on your end.

Our analogy isn't a perfect explanation of how webhooks work, but it helps paint the picture for why they're used. And webhooks can be used for a wide variety of reasons. For example, webhooks can be used to notify someone when a tweet is sent or to send an email about upcoming meetings. In the context of lending, webhooks can be used to notify a lender about loan events, like when a borrower misses a payment or when a charge is reversed.

However, if either the system sending a webhook or the system receiving it is down, the whole process doesn't work. Like any request sent over the web, a response is sent back to the sending program when the webhook notification is received. The possibility of failure to receive a webhook notification has prompted most webhook systems to employ a retry system that will keep sending the notification until a success response is received.

Webhook Security

The security of webhooks can be increased by including a security token of some kind. This is simply a string of characters the the receiver will recognize. Tokens allow the receiver to know if the webhook notification was what they are expecting, since any program could send anything to the webhook URL. It is also helpful if the webhook URL knows the IP address of potential senders of webhook notifications, so it can easily discriminate against notifications it receives from other sources.

A Note About DDoS Attacks
Distributed Denial of Service attacks happen when an open endpoint or other method for receiving data exists and a bad actor overloads it with messages. The result is that the program receiving the data spends a disproportionate amount of resources interpreting the malicious messages to the point that it hinders the performance of the programs primary function. DDoS attacks to webhook URLs can be mitigated by employing tokens and IP filtering.

Why are Webhooks Useful?

What makes webhooks so useful is their ease to set up. We use the word "ease" relatively because setting webhooks up from scratch definitely requires a bit of programming knowledge. But in comparison to creating an entire API, webhooks are a much easier option.

Webhooks are also useful because they don't require you to constantly request heaps of information from an API. Instead, webhooks send a single request that asks for specific information, alleviating server overload and your own stress.

Terminology

Here are some common terms 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.

timeouts

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

Remember our analogy from earlier? Let's break down how each of these terms fits into the analogy. As we said, our webhook is like an FBI surveillance team. The team is looking for some kind of activity in the form of an event or a trigger. When they see it, they immediately give you a call at your callback URL and include a payload of information describing what they saw. If they can't get a hold of you, they can retry the call at a different time. And if your phone continues to ring endlessly, they can decide to give up on the call and list it as a timeout.

This Feature is Not

Webhooks are not APIs. While webhooks are a useful (and easy) way to receive information, they are not as robust and versatile as entire APIs. APIs have the ability to add, update, or delete information, but webhooks can only send information to you. As such, they should not be used in replacement of a full API.

What's Next

At this point, you should have a foundational understanding of what webhooks are. If you feel ready, you can start creating your own webhooks with our help. To learn more about our reports feature where you can see a history of your webhook requests, consider reading our Reports Overview article. Lastly, if you're an admin and you'd like to restrict which of your users have access to webhooks, you can learn how to do so with our Agent User and User Roles functionalities.


How did we do?


Powered by HelpDocs (opens in a new tab)