Webhooks

Webhooks allow you to receive real-time notifications when events occur in LoanSense. Instead of polling our API, you register an endpoint URL and we POST event data to it as things happen.

Getting Started

To start receiving webhooks, contact us at dev@myloansense.com with:

• Your endpoint URL — the HTTPS URL where you want to receive webhook POSTs
• Which event types you want to subscribe to

We’ll provision a subscription and provide you with your webhook signing secret, which you’ll use to verify that incoming requests are genuinely from LoanSense.

Security

Signature Verification

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret. You should always verify this signature before processing the payload.

import crypto from "crypto";
 
function verifyWebhookSignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
 
  const a = Buffer.from(signature, "hex");
  const b = Buffer.from(expected, "hex");
 
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

Request Headers

Every webhook POST includes these headers:

Responding to Webhooks

Your endpoint should return a 200 status code to acknowledge receipt. If we receive a non-2xx response, the delivery will be marked as failed.

Event Types

loan.results.batch

Sent when a batch of processed loan results is ready. If a file contains more records than your configured batch size, results are split across multiple webhook deliveries. Use the batch_number and total_batches fields to reassemble the full result set.

In addition to the standard headers, batch webhooks include:

{
  "event": "loan.results.batch",
  "file_id": "file_abc123",
  "lender_id": "your-lender-id",
  "batch_number": 1,
  "total_batches": 3,
  "total_records": 487,
  "results": [
    {
      "borrower_id": "brw_0001",
      "loan_id": "LN-20260325-0042",
      "current_student_loan_payment": 450.00,
      "new_student_loan_payment": 280.00,
      "monthly_student_loan_payment_savings": 170.00,
      "current_dti": 0.42,
      "new_dti": 0.35,
      "lo": "Jane Smith",
      "lo_email": "jane.smith@lender.com",
      "met_criteria": "yes",
      "has_private_loans": "no",
      "loansense_link": "https://myloansense.com/c/YOURLENDER",
      "private_loan_link": null,
      "notes": ""
    }
  ],
  "timestamp": "2026-03-25T14:30:00Z"
}

Loan Result Schema

Each object in the results array contains:

borrower.status.updated

Sent when a borrower’s status changes in the LoanSense workflow. Borrowers progress through a 4-step process from initial signup through DTI recalculation readiness.

{
  "event": "borrower.status.updated",
  "lender_id": "your-lender-id",
  "borrower_id": "brw_0001",
  "loan_id": "LN-20260325-0042",
  "status": "appointment_scheduled",
  "step": 2,
  "previous_status": "consumer_signup",
  "previous_step": 1,
  "timestamp": "2026-03-25T10:15:00Z",
  "metadata": {
    "lo": "Jane Smith",
    "lo_email": "jane.smith@lender.com"
  }
}

Status Values

Borrowers progress through these statuses in order:

Example: Receiving Webhooks

A complete example of a webhook receiver in Node.js:

import crypto from "crypto";
import express from "express";
 
const app = express();
app.use(express.raw({ type: "application/json" }));
 
const WEBHOOK_SECRET = "{{WEBHOOK_SECRET}}";
 
app.post("/webhooks/loansense", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const event = req.headers["x-webhook-event"];
 
  // Verify signature
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");
 
  const a = Buffer.from(signature, "hex");
  const b = Buffer.from(expected, "hex");
 
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send("Invalid signature");
  }
 
  const payload = JSON.parse(req.body);
 
  switch (event) {
    case "loan.results.batch":
      console.log(
        `Received batch ${payload.batch_number}/${payload.total_batches}` +
        ` for file ${payload.file_id} (${payload.results.length} records)`
      );
      // Process loan results...
      break;
 
    case "borrower.status.updated":
      console.log(
        `Borrower ${payload.borrower_id} moved to` +
        ` ${payload.status} (step ${payload.step})`
      );
      // Update borrower status in your system...
      break;
  }
 
  res.status(200).json({ received: true });
});