Events

The configurator notifies your page when important things happen—when it's ready, when visitors progress, and when they complete the assessment. Use events to track engagement, capture leads, and trigger follow-up actions.

Why use events?

Events let you:

• Capture leads — Get notified when someone completes an assessment
• Track engagement — See how far visitors progress through the assessment
• Integrate with your CRM — Automatically create leads or opportunities
• Trigger follow-up — Send emails, schedule calls, or update dashboards
• Measure performance — Track conversion rates and drop-off points

Available events

Event	When it fires	Use case
onReady	Configurator has loaded	Show/hide loading states
onStepChange	Visitor moves to a new step	Track progress, update analytics
onComplete	Visitor finishes the assessment	Capture lead, trigger CRM workflow
onLeadSubmit	Visitor submits contact information	Primary lead capture event
onShare	Visitor shares or saves their assessment	Track sharing behavior

Listening to events

With data attributes (simple)

Add event handler attributes to your container element:

<div
  data-deep-fathom-onramp
  data-partner-id="your-partner-id"
  data-on-complete="handleComplete"
  data-on-lead-submit="handleLead"
></div>

<script>
  // These functions must be globally accessible
  function handleComplete(event) {
    console.log('Assessment completed:', event.detail);
  }

  function handleLead(event) {
    console.log('Lead captured:', event.detail);
    // Send to your CRM, analytics, etc.
  }
</script>

With JavaScript (flexible)

Listen to custom events on your container element:

const container = document.querySelector('[data-deep-fathom-onramp]');

container.addEventListener('deepfathom:complete', (event) => {
  const { sessionId, summary, handoffUrl, attribution } = event.detail;

  // Example: Send to your CRM
  fetch('/api/leads', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      source: 'onramp-kit',
      sessionId,
      summary,
      attribution,
    }),
  });
});

container.addEventListener('deepfathom:lead', (event) => {
  const { email, company, sessionId } = event.detail;
  console.log(`New lead: ${email} from ${company}`);
});

Iframe message events (advanced)

When the configurator runs in an iframe, events are delivered via postMessage. The SDK handles this automatically, but if you need direct access:

window.addEventListener('message', (event) => {
  // Always validate the origin
  if (event.origin !== 'https://onramp.deepfathom.ai') return;

  const { type, payload } = event.data;

  switch (type) {
    case 'deepFathom.onramp.complete':
      console.log('Assessment completed:', payload);
      break;
    case 'deepFathom.onramp.lead':
      console.log('Lead submitted:', payload);
      break;
    case 'deepFathom.onramp.resize':
      // Iframe height changed
      console.log('New height:', payload.height);
      break;
  }
});

Event payload

All events include a consistent payload structure:

interface EventPayload {
  // Session identifier (unique per assessment)
  sessionId: string;

  // Current step information
  stepId?: string;
  stepIndex?: number;

  // Sharing and handoff
  url?: string;           // Shareable link to this assessment
  snapshotId?: string;    // Snapshot ID (if snapshot service is configured)
  handoffUrl?: string;    // Full handoff URL with attribution

  // Attribution data
  attribution?: {
    partnerId?: string;
    referralCode?: string;
    source?: string;
    utmSource?: string;
    utmMedium?: string;
    utmCampaign?: string;
    utmContent?: string;
    utmTerm?: string;
  };

  // Assessment data
  summary?: {
    // Simplified results (company name, estimated level, etc.)
    [key: string]: unknown;
  };
  rawState?: {
    // Full assessment responses (if needed)
    [key: string]: unknown;
  };

  // Timestamp
  timestamp: string;  // ISO 8601 format
}

Example: onComplete payload

{
  "sessionId": "abc123-def456",
  "stepId": "summary",
  "stepIndex": 5,
  "url": "https://yoursite.com/assessment?df_snapshot=snap_789",
  "snapshotId": "snap_789",
  "handoffUrl": "https://app.deepfathom.ai/signup?df_snapshot=snap_789&partnerId=acme&utm_source=partner-site",
  "attribution": {
    "partnerId": "acme-security",
    "referralCode": "SPRING2025",
    "source": "deepfathom-onramp",
    "utmSource": "partner-site",
    "utmMedium": "embed"
  },
  "summary": {
    "companyName": "Acme Defense Corp",
    "estimatedLevel": "Level 2",
    "readinessScore": 42,
    "employeeCount": "50-200"
  },
  "timestamp": "2025-01-23T14:30:00Z"
}

Iframe message types

When using iframe mode, these are the raw message types:

Message type	Description
deepFathom.onramp.ready	Configurator initialized
deepFathom.onramp.step	Step changed
deepFathom.onramp.complete	Assessment completed
deepFathom.onramp.lead	Lead information submitted
deepFathom.onramp.share	Assessment shared
deepFathom.onramp.resize	Iframe height changed (includes height in pixels)

Common integrations

Google Analytics 4

container.addEventListener('deepfathom:complete', (event) => {
  gtag('event', 'cmmc_assessment_complete', {
    partner_id: event.detail.attribution?.partnerId,
    readiness_score: event.detail.summary?.readinessScore,
    estimated_level: event.detail.summary?.estimatedLevel,
  });
});

container.addEventListener('deepfathom:step', (event) => {
  gtag('event', 'cmmc_assessment_step', {
    step_id: event.detail.stepId,
    step_index: event.detail.stepIndex,
  });
});

HubSpot

container.addEventListener('deepfathom:lead', (event) => {
  const { email, company, summary } = event.detail;

  // Using HubSpot Forms API
  fetch('https://api.hsforms.com/submissions/v3/integration/submit/{portalId}/{formId}', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      fields: [
        { name: 'email', value: email },
        { name: 'company', value: company },
        { name: 'cmmc_readiness_score', value: summary?.readinessScore },
        { name: 'estimated_cmmc_level', value: summary?.estimatedLevel },
      ],
      context: {
        pageUri: window.location.href,
        pageName: document.title,
      },
    }),
  });
});

Webhook (generic)

container.addEventListener('deepfathom:complete', async (event) => {
  await fetch('https://your-webhook-endpoint.com/onramp-lead', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Webhook-Secret': 'your-secret',
    },
    body: JSON.stringify(event.detail),
  });
});

Troubleshooting

Events not firing

1. Check the console for errors during configurator initialization
2. Verify origin matching — Event handlers must be on the same page as the configurator
3. Confirm iframe mode — If using iframe, make sure you're listening to the correct element or window

Missing data in payload

• No snapshotId: Snapshot service not configured or failed. Check data-snapshot-endpoint.
• No handoffUrl: Handoff URL not configured. Set data-handoff-url.
• No attribution: Attribution parameters not set on container element.

Next steps

• Snapshots and sharing — Understand how assessments are saved and shared
• Embedding guide — Configure the full embed