Webhooks

Overview of how the Maxwell webhooks service works

Table of Contents

• Overview

  • Example

  • Flowchart of Webhook Service

• How Maxwell Webhook Events Work

  • Application File Creation

  • Application File Update

  • Loan File Status / Milestone Update

  • Webhook Events Schema

  • Example Event Request Body

• Instructions to Set Up Webhooks for Your Organization

• Other Details

  • Debouncing

  • Authentication

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.

Here is a flowchart of how our webhooks service works.

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

Field	Description	Type	Enumerations
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.	Data Schema	N/A
previousData	Previous values of the data points that have changed since the last webhook event.	Data Schema	N/A

Data Schema

Field	Description	Type	Enumerations
applicationFile	Application File values.	Application File Schema	N/A

Application File Schema

Field	Description	Type	Enumerations
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.	Subject Property Schema	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.	Address Schema	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

Field	Description	Type	Enumerations
address	The address of the subject property.	Address Schema	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

Field	Description	Type	Enumerations
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

// Create Event
{
  "id": "ff3533f2-a14b-44f2-b970-0054b8e97dc7",
  "type": "application_file.created",
  "data": {
    "applicationFile": {
      "id": 123456,
      "birthDate": null,
      "loanAmount": null,
      "downPayment": null,
      "jointCredit": false,
      "purposeType": null,
      "losLoanFileId": null,
      "purchasePrice": null,
      "baseLoanAmount": null,
      "hmdaGenderType": null,
      "mailingAddress": {
        "cityName": null,
        "lineText": null,
        "stateCode": null,
        "postalCode": null,
        "unitIdentifier": null
      },
      "subjectProperty": {
        "address": {
          "cityName": "Dawson",
          "lineText": "9991 Warford Street",
          "stateCode": "IA",
          "postalCode": "50066",
          "unitIdentifier": null
        },
        "propertyTypeName": null,
        "propertyUsageType": null
      },
      "borrowerLastName": "Firstimer",
      "borrowerFirstName": "Alice",
      "borrowerHomePhone": null,
      "borrowerWorkPhone": null,
      "militaryStatusType": null,
      "assignedPartyNmlsId": null,
      "borrowerMobilePhone": "2223334444",
      "borrowerEmailAddress": "[e-mail]",
      "borrowerAuthorizedCreditCheck": null,
      "cashOutDeterminationType": null
    }
  },
  "previousData": {
    "applicationFile": {}
  }
}

// Update Event
{
  "id": "0425f04d-a70d-4ec7-8909-7c32b1aaab02",
  "type": "application_file.updated",
  "data": {
    "applicationFile": {
      "id": 123456,
      "birthDate": null,
      "loanAmount": null,
      "downPayment": null,
      "jointCredit": false,
      "purposeType": null,
      "losLoanFileId": null,
      "purchasePrice": null,
      "baseLoanAmount": null,
      "hmdaGenderType": "Male",
      "mailingAddress": {
          "cityName": "Dawson",
          "lineText": "9992 Warford Street",
          "stateCode": "IA",
          "postalCode": "50066",
          "unitIdentifier": null
      },
      "subjectProperty": {
        "address": {
          "cityName": null,
          "lineText": null,
          "stateCode": null,
          "postalCode": null,
          "unitIdentifier": null
        },
        "propertyTypeName": null,
        "propertyUsageType": null
      },
      "borrowerLastName": "Firstimer",
      "borrowerFirstName": "Alice",
      "borrowerHomePhone": null,
      "borrowerWorkPhone": null,
      "militaryStatusType": null,
      "assignedPartyNmlsId": "098765",
      "borrowerMobilePhone": "2223334444",
      "borrowerEmailAddress": "[e-mail]",
      "borrowerAuthorizedCreditCheck": null,
      "cashOutDeterminationType": null
    }
  },
  "previousData": {
    "applicationFile": {
      "assignedPartyNmlsId": null,
      "hmdaGenderType": null,
      "mailingAddress": {
        "lineText": "9991 Warford Street"
      }
    }
  }
}

Instructions to set up Webhooks for Client Organizations

• Reach out to [e-mail] 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