Webhooks
Overview of how the Maxwell webhooks service works
Table of Contents
How Maxwell Webhook Events Work
Loan File Status / Milestone Update
Overview
Maxwell webhooks are designed to publish events occurring in our Point of Sale (POS) out to an external system. These events can be ingested and used however the receiver sees fit. This includes updating a lead generation system in a CRM, tracking when specific data points are filled out, etc. Any flow where it would be useful to know when application files from Maxwell's POS are created and subsequently certain data points within those applications are changed.
For Example:
Your organization uses dedicated CRM software to capture leads and their information prior to starting their mortgage loan application process. After you send them a referral link to start an application you'd like to keep track of what actions they took and get back some information from the POS and loan application to update your CRM data. In this case, you can set up webhook events to get updates on:
When a lead starts an application
When they update key sections of the application
When they submit their application
When their loan file changes milestones/statuses (e.g. document collection, underwriting, clear to close)
After your borrowers complete those actions in your POS Maxwell will post event updates to notify your system of user completed what event. Each update will contain the unique borrower email and loan file ID so you can match the users' identity between the POS and your CRM (or any other system we're linking to).
Data Flowchart
Below is a data flow chart for how the Maxwell Webhook service flows between our POS and your site's data.
How the Events Work
There are three types of events that our webhook service supports.
Application File Creation
Application Update (include application submission)
Loan file status / milestone update
Application File Creation
There will be an initial create event sent when an application file is marked as visible in the POS. This visible designation can be set through a variety of scenarios. The two most common scenarios are as follows:
An application file is started through the Lender Hub using the "New application" button.
An applicant who starts the application file through the Borrower Hub saves their progress by creating an account.
There will only ever be one create event per application file.
Application File Update
All of the data that is currently available, that adheres to the webhook schema, will be sent as part of this create event. For example, if an applicant fills out their name, cell phone number, and mailing address prior to the application file becoming visible, that data will be sent in the create event once they create an account.
If any of the fields listed below change there will be an update event that is sent.
These events are debounced with a wait period of 10 seconds so that there are less frequent events being sent.
Update events will not be sent until a create event has occurred.
Loan File Milestone / Status Updates
Webhook Events Schema
id
UUID that is associated with each event.
String
N/A
type
The type of webhook event that is being sent.
String
application_file.created application_file.updated
data
All current values.
N/A
previousData
Previous values of the data points that have changed since the last webhook event.
N/A
Data Schema
applicationFile
Application File values.
N/A
Application File Schema
id
Application File id in POS.
Number
N/A
assignedPartyNmlsId
The value for license of the primary agent on the application file. Only sent if a primary agent exists and there is a value for license.
String
N/A
baseLoanAmount
The base loan amount to be loaned to the borrower not including PMI, MIP, or Funding Fee.
Number
N/A
downPayment
The initial sum put down towards the loan by the borrower and co-borrowers.
Number
N/A
jointCredit
Indicates whether joint credit will be run by default for the application file.
Boolean
true false
loanAmount
The total amount for given loan.
Number
N/A
losLoanFileId
The loan file identifier in the LOS.
String
N/A
purchasePrice
The purchase price of the property for the loan application.
Number
N/A
purposeType
Specifies the purpose for which the loan proceeds will be used.
String
Purchase Refinance
subjectProperty
The collateral that is the subject property of the loan.
N/A
birthDate
Borrower's date of birth. Formatted YYYY-MM-DD. Primary borrower only.
String
N/A
borrowerAuthorizedCreditCheck
Indicates whether the borrower has authorized a credit check. Primary borrower only.
Boolean
true false
borrowerEmailAddress
The email address for the contact. Primary borrower only.
String
N/A
borrowerFirstName
The first name of the individual. Primary borrower only.
String
N/A
borrowerLastName
The last name of the individual Primary borrower only.
String
N/A
borrowerHomePhone
The individual's home phone number. Primary borrower only.
String
N/A
borrowerMobilePhone
The individual's mobile phone number. Primary borrower only.
String
N/A
borrowerWorkPhone
The individual's work phone number. Primary borrower only.
String
N/A
hmdaGenderType
Represents the borrower's or interviewer's statement about the borrower's gender. Primary borrower only.
String
Male Female ApplicantSelectedBothMaleAndFemale
mailingAddress
The mailing address of the primary borrower. Primary borrower only.
N/A
militaryStatusType
Specifies duty status of current or former military personnel. Primary borrower only.
String
ActiveDuty Other ReserveNationalGuardNeverActivated Separated Veteran
cashOutDeterminationType
A value from a MISMO prescribed list that classifies a refinanced loan
String
CashOut LimitedCashOut NoCashOut Unknown
Subject Property Schema
address
The address of the subject property.
N/A
propertyTypeName
Specifies the overall building type of the property.
String
N/A
propertyUsageType
Specifies the intended usage of the property by the borrower.
String
Investment Other PrimaryResidence SecondHome
Address Schema
cityName
The name of the city.
String
N/A
lineText
The address with the address number, pre-directional, street name, post-directional, address unit designators and address unit value.
String
N/A
stateCode
The two-character representation of the US state, US Territory, Canadian Province, Military APO FPO, or Territory.
String
N/A
postalCode
The postal code (ZIP Code in the US) for the address. ZIP Code may be either 5 or 9 digits.
String
N/A
unitIdentifier
The identifier value associated with the Secondary Address Unit Designator. Example: 123, C, B1C, etc.
String
N/A
Example Event Request Body
Instructions to set up Webhooks for Client Organizations
Reach out to help@himaxwell.com to let us know you're interested in setting up the service and work out an implementation and testing plan.
Setup a server to receive the requests with the above body. What the client does with the data is entirely up to them.
Select one of the authentication methods listed below and provide necessary data to Maxwell to add that authentication for you.
Ask Maxwell to turn on webhook events for a specific site, several sites, or the whole partner.
Test the webhook events to ensure that data is successfully pushed from the POS to your site.
Other Details
Debouncing
All of these events are debounced with a wait period of 10 seconds so fields changed near each other will result in less frequent events.
Authentication
There are a variety of ways for us to authenticate to the clients server that will receive the webhook event.
Custom SHA-256 HMAC Signature
Basic Auth
API Key
Bearer Token
OAuth2
AWS Signature
Last updated
