Say Goodbye to Polling in the Encompass Lending Platform - Part 1

November 05, 2018 | Sai Muralidharan

At Ellie Mae, we pride ourselves on being your technology partner to help you build, integrate and extend your digital mortgage universe. To further support you on your journey to the true digital mortgage and at the request of our developer community, we are launching a new “Developer Spotlight” blog series in which our technical experts will share insights into the hottest topics identified by you. This series will address new application programming interface (API) technologies, how they are impacting our industry, and the ways you can leverage them to rise above the competition. In this first ‘Developer Insights’ post, we explore the impact of Webhooks technology and how it can help you to more efficiently monitor changes that occur within your loans.

What are Webhooks and how do they work?

Thanks to the latest enhancements we’ve made to our Webhooks technology, available in Encompass Developer Connect™ Portal, there’s no longer a need to poll the Encompass Lending Platform™ to keep up with the most recent changes that have occurred within a loan. Webhooks provide real-time notifications of event changes within the platform without polling and without impacting the performance of the production instance.

Prior to the introduction of Webhooks, the only way to try to keep up with event, status and field changes was polling the Encompass Lending Platform’s production instance at regular intervals. A common practice was to run automated jobs that extract large volumes of data every 30 minutes or so. These types of jobs are very resource intensive and they can stress transactional systems, causing performance issues.

Webhooks, on the other hand, work in a way that is the reverse of most “POST” REST API calls, meaning that the Encompass Lending Platform will post notifications to the lender’s applications rather than the other way around. With Webhooks, instead of sending repeat requests for new events to the endpoint, you provide the endpoint with a URL in which it posts new event data and the lender application monitors that URL and is updated in real-time.

REST APIS:	LENDER APPLICATION --> ENCOMPASS LENDING PLATFORM
WEBHOOKS:	LENDER APPLICATION <-- ENCOMPASS LENDING PLATFORM

How to setup a Webhook subscription

Webhooks are subscription-based and once the subscription to a Webhook notification is setup, the Encompass Lending Platform will post a notification to the subscription endpoint for the corresponding event that is triggered in the production instance. Below is a walkthrough of the steps you will need to follow to setup your Webhook subscription.

1.Setting up Webhook notifications

To setup and subscribe to a Webhook, the APIs that are available in the Webhooks section of the Encompass Developer Connect Portal will need to be used. The first step of a Webhooks setup is to identify the event(s) that will be listened to.

The resources and events available for subscription are accessible via the “Get Resources” API call. For example, a “Loan Update” is a resource event. After the subscription is setup, the Encompass Lending Platform will post a message when a “Loan Update” event is triggered via the Smart Client, APIs, SDK, etc.

Separate subscriptions can be created for listening to each individual resource event or multiple resource events can be configured within one subscription. Note that there will be one notification sent for every subscription and these notifications are sent to the Webhook endpoint specified within the subscription.

2.Setting up a Webhook Endpoint to receive notifications

This is often referred to as a “Callback URL” or a “Webhook Endpoint”. This is a secure URL at the lender’s end to which the Encompass Lending Platform posts the event notifications. It is important that this is setup as a public URL and not behind any firewall. A client may choose to listen to different resource events in different URL endpoints, however, clients are required to use one domain name. If the URL becomes unavailable for any reason, the Encompass Lending Platform will make three attempts to deliver the notification.

3.Building a Webhook Listener Application

A Webhook Listener Application is a web application that listens to the public URL identified as the “Webhook Endpoint” in the above section and monitors the events posted by the Encompass Lending Platform. The events posted follow a generic structure and a sample is available in the Encompass Developer Connect Portal. The event notifications often contain references to a resource (e.g. Loan GUID) indicating that the corresponding event was triggered on that resource (e.g. loan), however the event notifications are not expected to contain any personally identifiable information (PII). Depending upon the criticality of these events, the client is expected to make the Webhook Listener Application highly available and resilient.

Since the events are configured to be posted to a public URL, it is essential to ensure that the messages posted are delivered by Ellie Mae and not by any other party. For security purposes, the system leverages a “Signature Validation” approach which validates the sender of each event notification. To validate the sender, every notification sent by the Encompass Lending Platform includes a signature (specifically located in the header section) that is encoded by a specific signing key. This signing key can be specified by the client as part of every subscription. If the client hasn’t specified the signing key, the default signing key can be obtained by placing a help-desk ticket. The Webhook Listener Application that the client has built is expected to check and validate the signature for every message, thereby, confirming that the notification was delivered by the Encompass Lending Platform.

Below is an example of the code used to create Webhook subscriptions. Once the subscription is setup, a response with a http status code of 201 should be received confirming the successful creation of your Webhook subscription. The subscription ID will be available in the response header under the “location” attribute. For more information, visit the Encompass Developer Connect Portal.

Subscription with individual events:

{ "events": ["create"], "endpoint": "https://webhook.abcmortgage.com/callback", "resource": "Loan" } Subscription with multiple events: { "events": ["create", "update"], "endpoint": "https://webhook.abcmortgage.com/callback", "resource": "Loan" }