Webhooks

Overview of how the Maxwell webhooks service works

Table of Contents

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 started 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

FieldDescriptionTypeEnumerations

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

FieldDescriptionTypeEnumerations

applicationFile

Application File values.

Application File Schema

N/A

Application File Schema

FieldDescriptionTypeEnumerations

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

Subject Property Schema

FieldDescriptionTypeEnumerations

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

FieldDescriptionTypeEnumerations

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": "engineering@himaxwell.com",
      "borrowerAuthorizedCreditCheck": 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": "engineering@himaxwell.com",
      "borrowerAuthorizedCreditCheck": null
    }
  },
  "previousData": {
    "applicationFile": {
      "assignedPartyNmlsId": null,
      "hmdaGenderType": null,
      "mailingAddress": {
        "lineText": "9991 Warford Street"
      }
    }
  }
}

Instructions to set up Webhooks for Client Organizations

  • 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.

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

PreviousReset PasswordNextEncompass e-Disclosure Integration

Last updated