Webhooks & Events

The widget communicates with the parent page via window.postMessage. All events are prefixed with bh: and include a type field.

Listening for events

There are two ways to receive events from the widget:

1. SDK callbacks (recommended)

Pass callback functions when initializing via the SDK. The SDK filters and dispatches events for you:

const widget = BHWidget.init({
  key: 'YOUR_KEY',
  type: 'auto',
  container: '#my-widget',
  onReady: () => {
    console.log('Widget loaded');
  },
  onStep: (step, name) => {
    console.log('Step', step, name);
  },
  onQuoteSubmitted: () => {
    console.log('Quotes requested');
  },
  onQuoteResults: (count) => {
    console.log('Received', count, 'quotes');
  },
  onNoQuotes: () => {
    console.log('No quotes available');
  },
  onError: (message) => {
    console.error('Error:', message);
  },
  onUserRegistered: (email) => {
    console.log('User registered:', email);
  },
  onResize: (height) => {
    console.log('Content height:', height);
  },
  onMessage: (data) => {
    console.log('Raw event:', data.type, data);
  },
  // Modal-only callbacks
  onOpen: () => {
    console.log('Modal opened');
  },
  onClose: () => {
    console.log('Modal closed');
  },
});

2. Raw postMessage listener

If using a direct iframe without the SDK, listen on the window:

window.addEventListener('message', (event) => {
  const data = event.data;

  // Only handle BenefitHub widget events
  if (!data || typeof data.type !== 'string' || !data.type.startsWith('bh:')) {
    return;
  }

  switch (data.type) {
    case 'bh:ready':
      console.log('Widget ready');
      break;
    case 'bh:step':
      console.log('Step', data.step, data.name);
      break;
    case 'bh:quote-submitted':
      console.log('Quote submitted');
      break;
    case 'bh:quote-results':
      console.log('Got', data.count, 'quotes');
      break;
    case 'bh:no-quotes':
      console.log('No quotes returned');
      break;
    case 'bh:error':
      console.error('Widget error:', data.message);
      break;
    case 'bh:user-registered':
      console.log('User:', data.email);
      break;
    case 'bh:resize':
      // Auto-resize the iframe
      document.querySelector('iframe').style.height = data.height + 'px';
      break;
  }
});

// Modal events are dispatched as CustomEvents (not postMessage)
window.addEventListener('bh:modal-open', () => {
  console.log('Modal opened');
});
window.addEventListener('bh:modal-close', () => {
  console.log('Modal closed');
});

SDK callback reference

3. CustomEvent listeners

When the SDK is loaded, it also dispatches events as CustomEvents on window, so you can listen with standard DOM APIs:

window.addEventListener('bh:quote-results', (event) => {
  const { count } = event.detail;
  console.log('Got', count, 'quotes');
});

window.addEventListener('bh:error', (event) => {
  console.error('Widget error:', event.detail.message);
});

Event Reference

Security considerations

When listening to postMessage events directly, always verify:

1. Event source: Check that event.source matches your widget iframe's contentWindow.
2. Event type prefix: Only process events where data.type starts with "bh:".

const iframe = document.querySelector('iframe');

window.addEventListener('message', (event) => {
  // Verify the message comes from our widget iframe
  if (event.source !== iframe.contentWindow) return;

  // Only handle BH events
  if (!event.data?.type?.startsWith('bh:')) return;

  // Safe to process
  handleWidgetEvent(event.data);
});

Analytics integration

Common pattern for tracking widget usage in Google Analytics, Segment, or similar:

const widget = BHWidget.init({
  key: 'YOUR_KEY',
  type: 'auto',
  container: '#widget',
  onStep: (step, name) => {
    gtag('event', 'insurance_step', {
      step_number: step,
      step_name: name,
    });
  },
  onQuoteSubmitted: () => {
    gtag('event', 'insurance_quote_submitted');
  },
  onQuoteResults: (count) => {
    gtag('event', 'insurance_quotes_received', {
      quote_count: count,
    });
  },
  onNoQuotes: () => {
    gtag('event', 'insurance_no_quotes');
  },
  onUserRegistered: (email) => {
    gtag('event', 'insurance_user_registered');
  },
});

Next steps

• Theming — customize widget appearance
• Embedding — integration options