Originator: Full Integration with Webhooks

Send cases and receive real-time updates on relay activity, invitations, and status.

---

🎯 Overview

📌 TL;DR

Send cases to Lexamica and get notified instantly when partners are matched, invitations are accepted/declined, and status updates are posted. Full visibility into the case lifecycle.

This guide is for you if:

• You send referrals to other firms via Lexamica

• You want real-time notifications for all case activity

• You need to keep your CRM or system in sync with Lexamica

What you'll build:

• Case and CaseInvitation mappings

• Send cases to the Relay Engine

• Webhook subscriptions for relay, invitation, and update events

• Multi-event webhook handler

What this does NOT cover:

• Receiving cases from other firms

• Responding to invitations (you're the sender, not receiver)

---

📖 Key Terms

Term	Definition
Originator	The firm that creates and sends out a case for referral
Relay Engine	Lexamica's automatic matching system that finds partner firms
Handler	The firm that accepts and handles the referred case

---

⚙️ Architecture

Full Originator Integration (Webhooks)
──────────────────────────────────────

          OUTBOUND                              INBOUND
          (You send cases)                      (Lexamica notifies you)

┌─────────────────┐                     ┌─────────────────┐
│   Your System   │                     │   Your System   │
│                 │                     │                 │
│ 1. Send case    │                     │ Webhook Handler │
│    via API      │                     │                 │
│                 │                     │ • Relay events  │
│ 2. Store        │                     │ • Invitation    │
│    case_id      │                     │   events        │
└────────┬────────┘                     │ • Update events │
         │                              └────────▲────────┘
         │ POST                                  │ POST
         ▼                                       │
┌─────────────────────────────────────────────────────────┐
│                   LEXAMICA                              │
│                                                         │
│  ┌───────────┐    ┌───────────┐    ┌───────────┐      │
│  │   Case    │───▶│   Relay   │───▶│ Invitation│      │
│  │  Created  │    │  Engine   │    │   Sent    │      │
│  └───────────┘    └───────────┘    └───────────┘      │
│                         │                │             │
│                         ▼                ▼             │
│              Events: Matched,    Events: Accepted,    │
│              Rejected, Missed    Declined, etc.       │
│                         │                │             │
│                         └────────────────┘             │
│                                  │                     │
│                                  ▼                     │
│                         Webhook Delivery ──────────────┼───▶
└─────────────────────────────────────────────────────────┘

---

📋 Prerequisites

Credentials:

• Organization ID, Public Key, and Private Key from Lexamica

Infrastructure:

• A publicly accessible HTTPS endpoint for webhooks

Foundational Docs:

• Organizations and Authentication — understand your API keys

• Mapping Engine — how field transformations work

• Inbound Webhooks — sending data to Lexamica

• Webhook Subscriptions — receiving events from Lexamica

---

💡 Step-by-Step Implementation

Step 1: Create Mappings

You'll need two mappings: one for Case data and one for CaseInvitation data.

Case Mapping (for sending and receiving case data):

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/mapping/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Case Mapping",
    "modelName": "Case",
    "fieldMappings": [
      { "lexamicaField": "_id", "foreignField": "lexamica_case_id", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "client.firstName", "foreignField": "client_first_name", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "client.lastName", "foreignField": "client_last_name", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "client.email", "foreignField": "client_email", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "client.phoneNumber", "foreignField": "client_phone", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "caseType", "foreignField": "practice_area", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "incident.date", "foreignField": "incident_date", "lexamicaFieldType": "Date", "foreignFieldType": "String" },
      { "lexamicaField": "incident.address.state", "foreignField": "incident_state", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "incident.synopsis", "foreignField": "description", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "customFields.crm_id", "foreignField": "crm_id", "lexamicaFieldType": "String", "foreignFieldType": "String" }
    ]
  }'

CaseInvitation Mapping (for invitation events):

curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/mapping/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Case Invitation Mapping",
    "modelName": "CaseInvitation",
    "fieldMappings": [
      { "lexamicaField": "_id", "foreignField": "invitation_id", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "referral._id", "foreignField": "case_id", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "invitee", "foreignField": "handler_firm_id", "lexamicaFieldType": "String", "foreignFieldType": "String" },
      { "lexamicaField": "accepted", "foreignField": "accepted_at", "lexamicaFieldType": "Date", "foreignFieldType": "String" },
      { "lexamicaField": "declined", "foreignField": "declined_at", "lexamicaFieldType": "Date", "foreignFieldType": "String" },
      { "lexamicaField": "declineReason", "foreignField": "decline_reason", "lexamicaFieldType": "String", "foreignFieldType": "String" }
    ]
  }'

Step 2: Create Webhook Subscriptions

Subscribe to the events you need to track.

Relay Events:

# Partner matched
curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/webhook-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case Relay Matched",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_case_mapping_id",
    "description": "Partner found for case",
    "active": true
  }'

# No partners available
curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/webhook-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case Relay Rejected",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_case_mapping_id",
    "description": "No partners available",
    "active": true
  }'

Invitation Events:

# Invitation accepted
curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/webhook-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case Invitation Accepted",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_invitation_mapping_id",
    "description": "Partner accepted case",
    "active": true
  }'

# Invitation declined
curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/webhook-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case Invitation Declined",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_invitation_mapping_id",
    "description": "Partner declined case",
    "active": true
  }'

Update and Settlement Events:

# Status updates
curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/webhook-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case Update Made",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_case_update_mapping_id",
    "description": "Status update posted",
    "active": true
  }'

# Settlement
curl -X POST \
  "https://integration.lexamica.com/organization/{orgId}/webhook-subscriptions/create" \
  -H "Authorization: Bearer your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Case Settlement",
    "url": "https://your-system.com/webhooks/lexamica",
    "secret": "your_webhook_secret",
    "mapping": "your_case_mapping_id",
    "description": "Case settlement started",
    "active": true
  }'

Step 3: Send Cases

Send cases using your Public Key (same as Lead Form Submission).

async function sendCase(caseData) {
  const response = await fetch(
    `${BASE_URL}/organization/${ORG_ID}/inbound-webhooks/case/${CASE_MAPPING_ID}/send?Key=${PUBLIC_KEY}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(caseData)
    }
  );
  
  const result = await response.json();
  
  // Store the case ID for correlation
  await saveCaseId(caseData.crm_id, result.lexamica_case_id);
  
  return result;
}

Step 4: Handle Webhooks

Build a handler that processes multiple event types.

---

🔧 Complete Code Example

const express = require('express');
const crypto = require('crypto');

const app = express();

app.use(express.json({
  verify: (req, res, buf) => { req.rawBody = buf; }
}));

const WEBHOOK_SECRET = process.env.LEXAMICA_WEBHOOK_SECRET;

// Verify signature
function verifySignature(rawBody, signature) {
  if (!signature) return false;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch { return false; }
}

// Event handlers
const handlers = {
  // Relay Events
  'Case Relay Matched': async (payload) => {
    console.log(`Case ${payload.lexamica_case_id} matched with partner`);
    await updateCase(payload.lexamica_case_id, {
      status: 'matched',
      matchedAt: new Date()
    });
  },
  
  'Case Relay Rejected': async (payload) => {
    console.log(`Case ${payload.lexamica_case_id} - no partners available`);
    await updateCase(payload.lexamica_case_id, {
      status: 'no_match',
      rejectedAt: new Date()
    });
    // Alert staff for manual handling
    await notifyStaff(`No partners found for case ${payload.lexamica_case_id}`);
  },
  
  'Case Relay Missed': async (payload) => {
    console.log(`Case ${payload.lexamica_case_id} - all partners declined`);
    await updateCase(payload.lexamica_case_id, {
      status: 'all_declined',
      missedAt: new Date()
    });
  },
  
  // Invitation Events
  'Case Invitation Accepted': async (payload) => {
    console.log(`Case ${payload.case_id} accepted by ${payload.handler_firm_id}`);
    await updateCase(payload.case_id, {
      status: 'accepted',
      handlerFirmId: payload.handler_firm_id,
      acceptedAt: payload.accepted_at
    });
  },
  
  'Case Invitation Declined': async (payload) => {
    console.log(`Case ${payload.case_id} declined: ${payload.decline_reason}`);
    await addCaseActivity(payload.case_id, {
      type: 'invitation_declined',
      reason: payload.decline_reason,
      date: payload.declined_at
    });
  },
  
  // Update Events
  'Case Update Made': async (payload) => {
    console.log(`Update on case ${payload.case_id}: ${payload.title}`);
    await addCaseActivity(payload.case_id, {
      type: 'status_update',
      title: payload.title,
      content: payload.content,
      date: new Date()
    });
  },
  
  // Settlement
  'Case Settlement': async (payload) => {
    console.log(`Case ${payload.lexamica_case_id} entering settlement`);
    await updateCase(payload.lexamica_case_id, {
      status: 'settling',
      settlementStarted: new Date()
    });
  }
};

// Main webhook endpoint
app.post('/webhooks/lexamica', async (req, res) => {
  const signature = req.headers['x-lexamica-signature'];
  const eventType = req.headers['x-lexamica-event'];
  
  if (!verifySignature(req.rawBody, signature)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Respond immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  const handler = handlers[eventType];
  if (handler) {
    try {
      await handler(req.body);
      console.log(`Processed: ${eventType}`);
    } catch (error) {
      console.error(`Failed to process ${eventType}:`, error);
    }
  } else {
    console.log(`Unhandled event: ${eventType}`);
  }
});

// Placeholder functions - implement for your system
async function updateCase(caseId, data) {
  console.log('Update case:', caseId, data);
}

async function addCaseActivity(caseId, activity) {
  console.log('Add activity:', caseId, activity);
}

async function notifyStaff(message) {
  console.log('Notify:', message);
}

app.listen(3000, () => console.log('Webhook server running'));

---

📋 Event Flow Reference

Event	When It Fires	What to Do
Case Relay Matched	Partner firm found	Update status to "Matched"
Case Relay Rejected	No partners available	Alert staff, may need manual handling
Case Relay Missed	Partners invited but all declined	Consider re-routing or manual handling
Case Invitation Accepted	Partner accepted the case	Update status, store handler info
Case Invitation Declined	Partner declined	Log reason, wait for other partners
Case Update Made	Handler posted status update	Sync to your system
Case Settlement	Settlement process started	Update status, track settlement

---

❓ FAQ

❓ "Do I need all these subscriptions?"

📝 Full Answer: No. Start with what you need:

• Minimum: Case Invitation Accepted (know when cases are handled)

• Recommended: Add Case Relay Rejected (know when matching fails)

• Full visibility: All events listed above

---

❓ "How do I correlate webhooks with my records?"

📝 Full Answer: Use the customFields.crm_id pattern:

1. When sending, include your CRM ID in customFields

2. This ID is returned in webhook payloads

3. Use it to find the matching record in your system

---

➡️ Next Steps

• Can't receive webhooks? See Originator: Full Integration with Polling

• Need to attach files? See File Operations

• Importing existing cases? See Import Existing Cases with Webhooks

---

Last updated: January 2026