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 and registers a deal
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 summary, trigger CRM workflow
`onDealRegistered`	Lead submitted and deal created	Primary lead capture with full context
`onShare`	Visitor shares or saves their assessment	Track sharing behavior

The DealRegistered event

When a visitor submits their email to register their assessment, the onDealRegistered event fires with complete deal information:

interface DealRegisteredPayload {
  sessionId: string;
  dealId: string;           // Unique deal identifier from Deep Fathom
  partnerVerified: boolean; // Whether your partner ID was recognized
  warnings: DealWarning[];  // Any soft validation issues

  lead: {
    email: string;
    company?: string;
  };

  context?: {
    // Assessment context (varies by tool)
    source?: string;        // e.g., "boundary-advisor"
    level?: string;         // e.g., "Level 2"
    timeline?: string;
    [key: string]: unknown;
  };

  attribution?: AttributionConfig;
  timestamp: string;
}

interface DealWarning {
  field: string;    // Which field triggered the warning
  code: string;     // Machine-readable warning code
  message: string;  // Human-readable description
}

Partner verification

The partnerVerified field indicates whether your partner ID is recognized in the Deep Fathom system:

true — Your partner ID is valid and the lead will be attributed to your account
false — Partner ID not recognized; check the warnings array for details

Even with partnerVerified: false, the deal is still created and you can still receive the lead data—it just won't be automatically attributed in Deep Fathom's partner portal.

Example: handling DealRegistered

import { mount } from '@onramp-kit/sdk';

mount('#configurator', {
  partnerId: 'your-partner-id',
  iframeSrc: 'https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html',

  onDealRegistered: (payload) => {
    console.log('Deal registered:', payload.dealId);

    // Check for warnings
    if (!payload.partnerVerified) {
      console.warn('Partner not verified:', payload.warnings);
    }

    // Send to your CRM
    fetch('/api/leads', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        dealId: payload.dealId,
        email: payload.lead.email,
        company: payload.lead.company,
        context: payload.context,
        attribution: payload.attribution,
      }),
    });
  },
});

Listening to events

With JavaScript SDK (recommended)

import { mount } from '@onramp-kit/sdk';

const handle = mount('#configurator', {
  partnerId: 'your-partner-id',
  iframeSrc: 'https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html',

  onReady: () => {
    console.log('Configurator loaded');
  },

  onStepChange: (payload) => {
    console.log('Step changed:', payload.stepId);
  },

  onComplete: (payload) => {
    console.log('Assessment completed:', payload.summary);
  },

  onDealRegistered: (payload) => {
    console.log('Deal registered:', payload.dealId);
    // Primary lead capture happens here
  },

  onShare: (payload) => {
    console.log('Assessment shared:', payload.url);
  },
});

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:

const iframeOrigin = new URL(
  'https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html',
).origin;

window.addEventListener('message', (event) => {
  // Always validate the origin
  if (event.origin !== iframeOrigin) return;

  const { type, payload } = event.data;

  switch (type) {
    case 'deepFathom.onramp.ready':
      console.log('Configurator ready');
      break;
    case 'deepFathom.onramp.complete':
      console.log('Assessment completed:', payload);
      break;
    case 'deepFathom.onramp.dealRegistered':
      console.log('Deal registered:', payload);
      // This is your primary lead capture event
      break;
    case 'deepFathom.onramp.resize':
      console.log('New height:', payload.height);
      break;
  }
});

Event payloads

ReadyPayload (onReady)

interface ReadyPayload {
  sessionId: string;
  timestamp: string;
}

EmbedEventPayload (onComplete, onStepChange, onShare)

interface EmbedEventPayload {
  sessionId: string;
  stepId?: string;
  stepIndex?: number;
  url?: string;           // Shareable link to this assessment
  snapshotId?: string;    // Snapshot ID (if snapshot service configured)

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

  summary?: {
    recommendedId?: string;
    recommendedTitle?: string;
    recommendedScore?: number;
    [key: string]: unknown;
  };

  rawState?: Record<string, unknown>;
  timestamp: string;
}

DealRegisteredPayload (onDealRegistered)

interface DealRegisteredPayload {
  sessionId: string;
  dealId: string;
  partnerVerified: boolean;
  warnings: Array<{
    field: string;
    code: string;
    message: string;
  }>;

  lead: {
    email: string;
    company?: string;
  };

  context?: Record<string, unknown>;
  attribution?: AttributionConfig;
  timestamp: string;
}

Example: onDealRegistered payload

{
  "sessionId": "abc123-def456",
  "dealId": "deal-789xyz",
  "partnerVerified": true,
  "warnings": [],
  "lead": {
    "email": "jane@acmedefense.com",
    "company": "Acme Defense Corp"
  },
  "context": {
    "source": "boundary-advisor",
    "level": "Level 2",
    "timeline": "standard",
    "recommendedArchetype": "Secure All"
  },
  "attribution": {
    "partnerId": "acme-security",
    "referralCode": "SPRING2025",
    "source": "deepfathom-onramp",
    "utmSource": "partner-site",
    "utmMedium": "embed"
  },
  "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.dealRegistered`	Deal registered (lead captured)
`deepFathom.onramp.share`	Assessment shared
`deepFathom.onramp.resize`	Iframe height changed (includes `height` in pixels)

Common integrations

Google Analytics 4

import { mount } from '@onramp-kit/sdk';

mount('#configurator', {
  partnerId: 'your-partner-id',
  iframeSrc: 'https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html',

  onComplete: (payload) => {
    gtag('event', 'cmmc_assessment_complete', {
      partner_id: payload.attribution?.partnerId,
      recommended_id: payload.summary?.recommendedId,
    });
  },

  onDealRegistered: (payload) => {
    gtag('event', 'cmmc_deal_registered', {
      deal_id: payload.dealId,
      partner_verified: payload.partnerVerified,
    });
  },

  onStepChange: (payload) => {
    gtag('event', 'cmmc_assessment_step', {
      step_id: payload.stepId,
      step_index: payload.stepIndex,
    });
  },
});

HubSpot

import { mount } from '@onramp-kit/sdk';

mount('#configurator', {
  partnerId: 'your-partner-id',
  iframeSrc: 'https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html',

  onDealRegistered: async (payload) => {
    const { lead, context, dealId } = payload;

    await 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: lead.email },
          { name: 'company', value: lead.company || '' },
          { name: 'cmmc_level', value: context?.level || '' },
          { name: 'deal_id', value: dealId },
        ],
        context: {
          pageUri: window.location.href,
          pageName: document.title,
        },
      }),
    });
  },
});

Webhook (generic)

import { mount } from '@onramp-kit/sdk';

mount('#configurator', {
  partnerId: 'your-partner-id',
  iframeSrc: 'https://cdn.deepfathom.ai/onramp-kit/v1/hosted/index.html',

  onDealRegistered: async (payload) => {
    await fetch('https://your-webhook-endpoint.com/onramp-lead', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Webhook-Secret': 'your-secret',
      },
      body: JSON.stringify({
        dealId: payload.dealId,
        email: payload.lead.email,
        company: payload.lead.company,
        context: payload.context,
        attribution: payload.attribution,
        partnerVerified: payload.partnerVerified,
        warnings: payload.warnings,
      }),
    });
  },
});

Troubleshooting

Events not firing

Check the console for errors during configurator initialization
Verify origin matching — Event handlers must be on the same page as the configurator
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 snapshotEndpoint config.
No attribution: Attribution parameters not set in config.
partnerVerified: false: Your partner ID is not recognized. Contact partners@deepfathom.ai.

Warnings in DealRegistered

Common warning codes:

Code	Meaning
`unknown_partner`	Partner ID not found in system
`missing_partner`	No partner ID provided
`missing_partner_name`	No partner name provided

These are non-blocking—the deal is still created, but attribution may be incomplete.

Next steps

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

Why use events?​

Available events​

The DealRegistered event​

Partner verification​

Example: handling DealRegistered​

Listening to events​

With JavaScript SDK (recommended)​

Iframe message events (advanced)​

Event payloads​

ReadyPayload (onReady)​

EmbedEventPayload (onComplete, onStepChange, onShare)​

DealRegisteredPayload (onDealRegistered)​

Example: onDealRegistered payload​

Iframe message types​

Common integrations​

Google Analytics 4​

HubSpot​

Webhook (generic)​

Troubleshooting​

Events not firing​

Missing data in payload​

Warnings in DealRegistered​

Next steps​