Skip to main content

Authenticated Partner Ingestion API (HMAC)

External agency management platforms (Falcon Agency Management, partner brokerages, dealership networks) push qualified personal and commercial trucking insurance leads into HiTech Insurance via dedicated, cryptographically signed REST endpoints:

  • Personal Lines Endpoint: POST https://hitechinsurance.ai/api/leads/personal
  • Commercial Trucking Endpoint: POST https://hitechinsurance.ai/api/leads/commercial-trucking

1. Cryptographic Authentication & Security Handshake​

Inbound requests bypass traditional cookie or session authentication in favor of HMAC-SHA256 (Hash-Based Message Authentication Code) using a shared secret key configured in HTI_LEAD_HMAC_SECRET.

1.1 Required HTTP Headers​

HeaderTypeDescription
Content-TypestringMust be application/json.
X-HTI-TimestampstringUnix epoch timestamp in seconds. Replay attack defense: must be within ±5 minutes (300 seconds) of the server UTC clock.
X-HTI-SignaturestringLowercase hexadecimal HMAC-SHA256 signature calculated over ${X-HTI-Timestamp}.${rawRequestBody}.

1.2 Verification Algorithm (src/lib/hti-leads/verify.ts)​

// Architectural Implementation: HMAC-SHA256 Verification
export function verifyHtiSignature(
  rawBody: string,
  timestampHeader: string | null,
  signatureHeader: string | null
): { valid: boolean; reason?: string } {
  const secret = process.env.HTI_LEAD_HMAC_SECRET;
  if (!secret) {
    return { valid: false, reason: "Server misconfiguration: HTI_LEAD_HMAC_SECRET is missing." };
  }

  if (!timestampHeader || !signatureHeader) {
    return { valid: false, reason: "Missing required X-HTI-Timestamp or X-HTI-Signature headers." };
  }

  // 1. Replay Attack & Clock Drift Check (300 seconds window)
  const timestamp = parseInt(timestampHeader, 10);
  const now = Math.floor(Date.now() / 1000);
  if (isNaN(timestamp) || Math.abs(now - timestamp) > 300) {
    return { valid: false, reason: "Timestamp expired or clock skewed beyond +/- 5 minutes." };
  }

  // 2. Compute Expected Signature
  const stringToSign = `${timestampHeader}.${rawBody}`;
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(stringToSign)
    .digest("hex");

  // 3. Timing-Safe Comparison to Prevent Side-Channel Attacks
  const isValid = crypto.timingSafeEqual(
    Buffer.from(signatureHeader, "utf-8"),
    Buffer.from(expectedSignature, "utf-8")
  );

  return isValid
    ? { valid: true }
    : { valid: false, reason: "HMAC signature mismatch." };
}

2. Inbound Lead Payloads & Schemas​

2.1 Personal Lines Lead (POST /api/leads/personal)​

Accepts full personal auto, home, renters, or motorcycle records transferred from Falcon CRM:

{
  "lead": {
    "id": "clx_pers_987654",
    "firstName": "Jane",
    "lastName": "Doe",
    "middleName": "Ann",
    "addressStreet1": "123 Main St",
    "addressStreet2": "Apt 4B",
    "addressCity": "Austin",
    "addressCounty": "Travis",
    "addressState": "TX",
    "addressZipCode": "78701",
    "contactInformationEmailAddress": "jane.doe@example.com",
    "contactInformationMobilePhone": "+15125551234",
    "declinedEmail": false,
    "declinedPhone": false,
    "monthsAtResidence": 12,
    "numberOfResidentsInHousehold": 3,
    "priorInsuranceInformationPriorInsurance": true,
    "priorInsuranceInformationPriorCarrierId": "carrier_tx_091",
    "priorInsuranceInformationPriorExpirationDate": "2026-10-15T00:00:00.000Z",
    "priorInsuranceInformationPriorLiabilityLimit": "100/300/100",
    "priorInsuranceInformationPriorMonthsCoverage": 36,
    "referredBy": "Falcon Referral Network",
    "insuranceLineType": "Personal Auto"
  },
  "user": {
    "id": "cly_user_112233",
    "email": "jane.doe@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "phone": "+15125551234"
  }
}

2.2 Commercial Trucking Lead (POST /api/leads/commercial-trucking)​

Accepts complex fleet and owner-operator freight data:

{
  "lead": {
    "id": "clx_truck_554433",
    "companyName": "Lone Star Express Logistics LLC",
    "companyDBA": "Lone Star Freight",
    "usDot": "3849102",
    "mcNumber": "MC-994821",
    "einNumber": "84-9928172",
    "yearsInBusiness": 4,
    "numberOfPowerUnits": 5,
    "numberOfTrailers": 8,
    "radiusOfOperation": "500+ miles (Interstate Long Haul)",
    "cargoTypes": ["General Freight", "Refrigerated Food"],
    "addressStreet1": "890 Industrial Blvd",
    "addressCity": "Fort Worth",
    "addressState": "TX",
    "addressZipCode": "76102",
    "contactInformationEmailAddress": "dispatch@lonestarfreight.com",
    "contactInformationMobilePhone": "+18175550987",
    "insuranceLineType": "Commercial Trucking - Auto Liability & Cargo"
  },
  "user": {
    "id": "cly_user_998877",
    "email": "dispatch@lonestarfreight.com",
    "firstName": "Carlos",
    "lastName": "Rodriguez",
    "phone": "+18175550987"
  }
}

3. Storage & Idempotent Upsert Logic​

When a verified request enters the route handler:

  1. Idempotent Lookup: The handler queries HtiLead.findOne({ externalLeadId: data.lead.id }).
  2. Upsert or Insert:
    • If an existing record exists, it updates normalized attributes and appends to the history log.
    • If new, it creates a fresh HtiLead document with status: 'received'.
  3. 100% Payload Preservation: The complete, unstripped JSON payload is saved in the completePayload field and rawPayload field. No vendor parameters are discarded.
  4. Admin Notification: Dispatches an internal alert to agency underwriters notifying them that an authenticated partner lead was ingested.

4. HTTP Status & Error Codes​

StatusCodeMeaning & Diagnostic
HTTP 201 CreatedSUCCESSLead received, verified, normalized, and persisted into HtiLead.
HTTP 400 Bad RequestINVALID_PAYLOADRequest body is not valid JSON or lacks mandatory root attributes (lead).
HTTP 401 UnauthorizedSIGNATURE_MISMATCHComputed HMAC signature did not match X-HTI-Signature header.
HTTP 401 UnauthorizedTIMESTAMP_EXPIREDX-HTI-Timestamp differs from server UTC clock by more than 300 seconds.
HTTP 429 Too Many RequestsRATE_LIMITEDSubmitting IP address exceeded the STANDARD_API limit (100 req / min).
HTTP 500 Internal ErrorDATABASE_ERRORMongoDB connection timeout or schema write failure.