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

November 13, 2018 | Sai Muralidharan

In our last Developer Spotlight blog, we addressed the impact of Webhooks technology and how it can help you to more efficiently monitor changes that occur within your loans. In this next blog, we will explore this topic one step deeper and address what Webhook updates were a part of our recent Encompass Lending Platform release.

In the recent release, a new loan “change” event was added as part of our Webhook notifications. Unlike the existing loan “save” notification, this new event notification allows a client to listen for specific changes within their loans and include the specific field details as part of the subscription.

Subscribing to the “Change” Event Notifications:

In addition to specifying the resource, event and endpoint attributes, this “change” subscription requires the client to include a “filter” attribute. The filter attribute accepts JSON Paths for attributes as inputs. More than one attribute’s JSON Path may be specified and multiple attributes will be treated with the “OR” logical condition – meaning that it will trigger the notification if attribute 1 or attribute 2 changes.

Creating a Change Subscription:

The difference between the “change” subscription and other subscriptions is the “filter” attribute. The JSON Paths of the attributes are specified within this filter attribute. A new schema application programming interface (API) has been provided to create reference JSON Paths, based on a field ID or a field name. Note that the attribute JSON Paths will accept “*” as a wildcard when referencing items in a collection or list. Running the below new schema API will result in JSON Paths for the field IDs sent in the request.

API: https://api.elliemae.com/encompass/v1/schema/loan/... METHOD: POST

Below is a request for retrieving the JSON Paths for field IDs 2, 5 and 60.

[ "2","5","60" ] And here is the response to the above request. { "2": "/baseLoanAmount", "5": "/principalAndInterestMonthlyPaymentAmount" "60": "/applications/*/coborrower/experianCreditScore" }

With the result above as a reference, a change subscription can be created with the API request below.

API: https://api.elliemae.com/webhook/v1/subscriptions METHOD: POST

The request payload is shown below.

{ "events": [ "change" ], "filters": { "attributes": [ "/baseLoanAmount", "/principalAndInterestMonthlyPaymentAmount", "/applications/*/coborrower/experianCreditScore" ] }, "endpoint": "https://mydomain.com/loan/change1", "resource": "Loan" }

With the above subscription, the Encompass Lending Platform will scan for changes in those three attributes whenever a loan is changed. This is done in two steps:

1.For every loan that is updated, a comparison is made between the new “updated” version and the previous version of any loan to create a changeset. This changeset includes all attributes that were changed as part of the “loan update”.

2.This changeset will be compared against all the “change” subscriptions. Upon finding a matching subscription, a notification will be posted in the configured endpoint URL.

Note: For field IDs such as 87, that have JSON Paths with the value references below, the subscription can be accepted only at the collection level.

"87": "/contacts[?(@/contactType == \"ESCROW_COMPANY\")]/email" "filters": { "attributes": [ "/contacts/*/email" ] }

Common Use Cases:

One of the common use cases for this “change” subscription is monitoring changes to a milestone and sending an email reminder to the loan associate assigned to the subsequent milestone that was changed. Some other common use cases include ordering a Loan Product Advisor (LPA) for every loan with a Desktop Underwriter (DU) order, monitoring change in the base loan amount, and monitoring change in disclosure tracking.

Use Case Example: Creating a change subscription based on the “doneIndicator” attribute of all the milestones.

{ "events": [ "change" ], "filters": { "attributes": [ "/milestoneLogs/*/doneIndicator" ] }, "endpoint": "https://mydomain.com/loan/mileStonechange", "resource": "Loan" }

Best Practices:

Our technical experts have recommended a few best practices for developers using this new “change” subscription. Note that you cannot include more than 50 attributes as part of a single subscription, but you may add more than one “change” subscription. When delivering different subscriptions at different endpoints, the resource event and the endpoint combination must be unique. And lastly, remember that upfront testing is required to ensure that the notifications are being posted to the right endpoint.