Templates / Build with Komo / Integration Recipes

Integration Recipes

Build with Komo

Step-by-step guides for SSO, CRM sync, event app embed, and sponsor lead export.

Template Content

~2698 words, 430 lines

## Integration Recipes

Step-by-step guides for the most common Komo integrations. Each recipe covers what it solves, the approach, and the exact steps to implement.

### Recipe Overview

- **SSO Setup** (Medium) -- Authenticate users seamlessly so they don't re-login when entering Komo experiences. JWT-based Single Sign-On via the embed SDK. Tags: Embed SDK, Authentication, JWT.
- **Event App Embed** (Medium) -- Add Komo's interactive engagement layer to an existing event platform (Eventbase, Bizzabo, etc.) via WebView or iframe. Tags: Embed SDK, SSO, Events.
- **CRM & API Integration** (Easy-Advanced) -- Push data to any external system. Built-in connectors for Salesforce, Mailchimp, and Braze -- plus custom HTTP requests for any REST API. Webhooks for full server-side control. Tags: Workflows, Salesforce, Mailchimp, Braze, HTTP / Webhooks.
- **Sponsor Lead Export** (Medium) -- Generate per-sponsor lead reports from branded activations. Segment leads by sponsor using card-scoped data, tags, and workflow filters. Tags: Workflows, Contacts, Competitions.

Don't see what you need? Check Workflow Patterns for automation-focused guides.

---

## SSO Setup

Authenticate users in Komo automatically so they never see a login screen. Users authenticated in your app are seamlessly authenticated in the embedded Komo experience.

### Use Case

Your users are already logged into your event app, loyalty platform, or website. When they interact with an embedded Komo card, you don't want them to see a second login form. SSO passes their identity to Komo so the experience feels native -- one session, one identity.

### Approach

Komo SSO uses **JWT (JSON Web Token)** authentication via the embed SDK. The flow is:

1. User logs into **your app** (your existing auth system)
2. Your backend generates a **JWT** that Komo can verify (using a shared secret or public key configured in the Komo Portal)
3. Your frontend passes the JWT to the **Komo Embed SDK**
4. Komo verifies the JWT and authenticates the user -- **no login screen shown**

### Implementation Steps

#### 1. Configure SSO in the Komo Portal

In the Komo Portal, navigate to your Site's settings and enable SSO authentication. Configure the signing secret or public key that Komo will use to verify your JWTs. Note the expected JWT claims (subject, email, name fields).

#### 2. Generate JWTs on Your Backend

When a user is authenticated in your system, generate a JWT containing their identity. The JWT payload should include the claims Komo expects:

```javascript
// Node.js example using jsonwebtoken
const jwt = require('jsonwebtoken');

function generateKomoToken(user) {
  const payload = {
    sub: user.id,            // Unique user identifier
    email: user.email,       // User's email
    first_name: user.firstName,
    last_name: user.lastName
  };

return jwt.sign(payload, KOMO_SSO_SECRET, {
    expiresIn: '1h',
    issuer: 'your-app-name'
  });
}
```

#### 3. Pass the Token via the Embed SDK

On the frontend, pass the JWT to Komo using `setAuthToken`. Call this after the embed script loads and before the user interacts with a card.

```javascript
// Option A: Set the token directly (if you already have it)
const token = await fetch('/api/komo/auth-token')
  .then(res => res.json())
  .then(data => data.token);

komoEmbed.setAuthToken(token);
```

#### 4. Handle Auth Requests (Recommended)

For a more robust approach, use `setAuthRequestHandler`. Komo calls this handler when it needs authentication -- this handles token expiration and lazy loading gracefully.

```javascript
komoEmbed.setAuthRequestHandler(async function() {
  // This is called when Komo needs the user to be authenticated.
  // Fetch a fresh JWT from your backend.
  const response = await fetch('/api/komo/auth-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId: currentUser.id,
      email: currentUser.email
    })
  });

if (!response.ok) {
    throw new Error('Failed to get auth token');
  }

const data = await response.json();
  return data.token;  // Return the JWT string
});
```

**Recommended:** `setAuthRequestHandler` is the preferred approach. It handles token refresh automatically and only requests a token when Komo actually needs one.

#### 5. Handle Logout

When the user logs out of your app, clear their Komo session:

```javascript
function onUserLogout() {
  // Clear your app's session
  clearSession();

// Clear Komo's session
  komoEmbed.forgetUser();
}
```

### Testing

1. Log into your app as a test user
2. Open a page with an embedded Komo card
3. Click the card -- it should open without showing a login form
4. Submit a form in the card -- the contact should be created with the user's identity from the JWT
5. Check the Komo Portal's Contacts section to verify the user appears with the correct email and name

For the full authentication reference, see the Embed SDK authentication docs at developers.komo.tech/embedding/browser.

---

## Event App Embed

Add Komo's interactive engagement layer to an existing event platform -- Eventbase, Bizzabo, Swapcard, or any app with a WebView or iframe capability.

### Use Case

Your client already has an event platform for scheduling, networking, and logistics. They want to add interactive engagement -- trivia, polls, sponsor activations, scavenger hunts, leaderboards -- without replacing the event app. Komo embeds directly into the existing app, adding the engagement layer without disrupting the core experience.

### Approach

Most event platforms support either a **WebView** (for native apps) or an **iframe** (for web-based apps). The Komo Embed SDK works in both contexts.

- **WebView Approach** -- Create a page in your event app that loads via WebView. This page includes the Komo embed script and renders cards or the full hub. The WebView handles all Komo UI.
- **iframe Approach** -- Embed the Komo Hub URL directly as an iframe within the event platform's UI. Simpler setup, but less control over the integration.

### Implementation Steps

#### 1. Add the Embed Script

Create an HTML page (or add to an existing page within your event app) that includes the Komo embed script:

```html
<!DOCTYPE html>
<html>
<head>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <script
    src="https://yourevent.komo.site/webembed/embed.js"
    data-komo-hub-url="https://yourevent.komo.site"
    async
  ></script>
</head>
<body>
  
  <div data-komo-embed-card-cover="CARD_ID"></div>
</body>
</html>
```

#### 2. Configure SSO Passthrough

Pass the event app user's identity to Komo so they don't see a login screen. Use the auth request handler pattern:

```javascript
// Get the user's identity from the event app
const eventUser = EventAppSDK.getCurrentUser();

komoEmbed.setAuthRequestHandler(async function() {
  // Call your backend to generate a Komo JWT
  const response = await fetch('/api/komo/auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId: eventUser.id,
      email: eventUser.email,
      name: eventUser.displayName
    })
  });
  const data = await response.json();
  return data.token;
});

// Also prefill forms with known user data
komoEmbed.setFormPrefillValues({
  'email': eventUser.email,
  'first_name': eventUser.firstName,
  'last_name': eventUser.lastName,
  'company': eventUser.company
});
```

#### 3. Embed Cards or the Full Hub

Choose your embedding strategy based on the event app's UI:

- **Full Hub:** Best for a dedicated "Engagement" or "Activities" tab in the event app. Renders all cards, navigation, and leaderboards.
- **Individual Cards:** Best for embedding specific activations within existing screens -- a trivia card on the session page, a poll on the sponsor page, etc.

#### 4. Listen for Events

Use event listeners to react to Komo activity -- update the event app UI, log analytics, or trigger in-app notifications:

```javascript
komoEmbed.listenToKomoEvents(function(event) {
  if (event.type === 'Gameplay.Ended') {
    // Update the event app's activity feed
    EventAppSDK.logActivity('Completed Komo challenge');
  }

if (event.type === 'Prize.Won') {
    // Show a native notification
    EventAppSDK.showNotification('You won a prize!');
  }
});
```

#### 5. Pass Extension Data

Tag Komo interactions with event context so you can correlate data across systems:

```javascript
komoEmbed.setExtensionDataValues({
  'event_id': 'conf-2025',
  'attendee_id': eventUser.id,
  'ticket_type': eventUser.ticketType,
  'session_id': currentSession.id
});
```

### Key Considerations

- **Connectivity Optimization** -- Event venues often have unreliable WiFi. Komo experiences are lightweight and designed for mobile, but test with throttled connections. Consider preloading the embed script and card assets when the user first enters the app, not when they navigate to the engagement section.
- **SSO Handoff** -- The SSO flow must be seamless. If the JWT generation fails or takes too long, the user will see a Komo login form -- a poor experience. Implement error handling and consider pre-generating the JWT when the user logs into the event app, not on first Komo interaction.
- **Branding Consistency** -- Configure the Komo Hub's theme to match the event app's branding -- colors, fonts, and logos. This makes the embedded experience feel native rather than a third-party widget. Theme settings are in the Komo Portal under Site > Design.

---

## CRM & API Integration

Komo's Workflow engine lets you set up triggers based on user actions and automatically push data to external systems. Many popular services have built-in connected apps -- for everything else, you can make custom HTTP requests to any API.

### How It Works

Every Komo integration follows the same pattern: **a trigger fires, then one or more actions execute**. You configure this in the Komo Portal under Automation > Workflows -- no code required for built-in integrations.

```
Trigger                          Action(s)
─────────────────────    -->    ─────────────────────
User submits form                Salesforce: Create Lead
User wins prize                  Mailchimp: Tag Subscriber
Coupon redeemed                  HTTP Request: POST to your API
Gameplay ended                   Braze: Track User
```

### Available Triggers

These are the events that can kick off a workflow. You can scope any trigger to a specific card, site, or the entire workspace.

- **Gameplay.DataCaptured** -- User submits a form within a card. Contains all form field values.
- **Gameplay.DataCapturedQualified** -- Qualified submission -- user meets eligibility criteria you've defined.
- **Gameplay.Ended** -- Card experience finished. Contains gameplay results and score.
- **Prize.Won** -- User won a prize. Contains prize details and winner info.
- **Coupon.Redeemed** -- Digital coupon was redeemed. Contains coupon and contact data.
- **Contact.Created** -- New contact created in Komo. Useful as a catch-all sync trigger.

### Built-in Connected Apps

These platforms have native integrations in Komo -- select them as workflow actions and map fields directly in the UI. No HTTP configuration, no code.

**Salesforce:**

- **Get Object** -- query existing records
- **Create Object** -- create Leads, Contacts, etc.
- **Update Object** -- update existing records

**Mailchimp:**

- **Upsert Subscriber** -- add or update list members
- **Tag Subscriber** -- apply tags for segmentation

**Braze:**

- **Track User** -- update user profiles and attributes

**Tip:** Built-in apps handle authentication, retry logic, and field mapping for you. Always use a connected app when one exists for your service -- it's faster and more reliable than a custom HTTP request.

### Custom HTTP Requests (Any API)

For services without a built-in connector -- HubSpot, Zoho, Klaviyo, your own backend, or any REST API -- use the **HTTP Request** action. It can call any URL with custom method, headers, body, and authentication.

```
// Example: Push a lead to HubSpot via HTTP Request action
Method: POST
URL: https://api.hubspot.com/crm/v3/objects/contacts
Headers:
  Authorization: Bearer YOUR_HUBSPOT_TOKEN
  Content-Type: application/json
Body:
{
  "properties": {
    "email": "{{ contact.email }}",
    "firstname": "{{ contact.first_name }}",
    "lastname": "{{ contact.last_name }}",
    "lead_source": "Komo - {{ card.name }}",
    "komo_score": "{{ gameplay.score }}",
  }
}
```

The `{{ field.name }}` placeholders are template variables -- Komo replaces them with real values from the trigger event when the workflow runs.

**This covers any integration need.** If a service has a REST API, you can connect Komo to it. Common examples: push leads to HubSpot, send events to Segment, update records in Airtable, trigger Slack notifications, call your own microservice.

### Webhooks (Server-Side Event Stream)

For scenarios where you need your own backend to receive and process events -- complex business logic, multi-destination routing, data enrichment -- Komo can also send webhook POST requests directly to your endpoint.

- **Site Events** -- Site published, unpublished
- **Prize Events** -- Prize won, claimed, draw completed
- **Form Events** -- Form submitted, data captured, qualified
- **Card & Coupon Events** -- Gameplay started/ended, coupon issued/redeemed

Configure webhook URLs in the Komo Portal under Settings > Webhooks. Your endpoint receives a JSON POST for each event, which you can then transform and route however you need.

### Choosing the Right Approach

| Approach | Best for | Setup |
|---|---|---|
| Built-in App | Salesforce, Mailchimp, Braze -- standard sync | No-code, 5 minutes |
| HTTP Request | Any REST API -- HubSpot, Klaviyo, Airtable, custom | No-code, 10-15 minutes |
| Webhooks | Complex logic, enrichment, multi-destination routing | Requires your own backend |

You can use all three simultaneously. For example: built-in Salesforce sync for leads, an HTTP Request to Slack for notifications, and webhooks to your analytics pipeline.

### Field Mapping

When configuring any action, you map Komo data to the destination's fields. Here's an example for a Salesforce Lead:

| Komo Field | Destination Field |
|---|---|
| `contact.email` | Email |
| `contact.first_name` | FirstName |
| `contact.last_name` | LastName |
| `form_fields.company` | Company |
| `card.name` | LeadSource |

Full webhook event reference: developers.komo.tech/webhook-events

---

## Sponsor Lead Export

Generate per-sponsor lead reports from branded activations. Each sponsor at an event gets their own filtered set of leads from their specific Komo cards.

### Use Case

You're running an event with multiple sponsors. Each sponsor has their own branded Komo activations -- Sponsor A has a trivia card, Sponsor B has a spin-to-win, Sponsor C has a poll. After the event, each sponsor needs a report of the leads who engaged with *their* activation -- not everyone else's. You need to segment and export leads by sponsor.

### Approach

The key pattern is: **sponsor-branded cards -> tagged entries -> filtered export**. Each sponsor's activations are separate cards. Entries are automatically scoped to the card they came from. Workflows, manual exports, or the API can filter by card or tag.

```
Sponsor A Card --> Entries tagged "sponsor-a" --> Export: Sponsor A Leads
Sponsor B Card --> Entries tagged "sponsor-b" --> Export: Sponsor B Leads
Sponsor C Card --> Entries tagged "sponsor-c" --> Export: Sponsor C Leads
```

### Implementation Steps

#### 1. Create Sponsor-Branded Cards

In the Komo Portal, create separate cards for each sponsor. Name them clearly (e.g., "Sponsor A Trivia", "Sponsor B Spin-to-Win"). Each card can have its own branding, cover image, and data capture form. The card itself serves as the natural segmentation boundary.

#### 2. Tag Entries by Sponsor

Use Komo Workflows to automatically tag contacts when they engage with a sponsor's card:

**Workflow: Tag Sponsor A Leads**

- **Trigger:** Gameplay.DataCaptured (scoped to Sponsor A's card)
- **Action:** Update Contact -> Add tag "sponsor-a"

Repeat this workflow for each sponsor. Tags make it easy to filter contacts in the portal and via the API.

#### 3. Export Options

There are multiple ways to get the per-sponsor lead data out of Komo:

- **Option A: Manual Export from Portal** -- Go to Contacts in the Komo Portal, filter by tag (e.g., "sponsor-a"), and export as CSV. Quick and simple for one-time reports.
- **Option B: Workflow to Sponsor's CRM** -- Create a workflow that triggers on the sponsor's card and sends the data directly to the sponsor's CRM or webhook endpoint. Real-time -- leads flow as they're captured.
- **Option C: API Export** -- Use the Komo API to programmatically pull contacts filtered by tag or card. Automate the export on a schedule or trigger it from your own system.

#### 4. Workflow: Route Leads to Sponsor Webhook

For real-time lead delivery to sponsors, set up a workflow that forwards data to their endpoint:

**Workflow: Route Sponsor A Leads**

- **Trigger:** Gameplay.DataCapturedQualified (scoped to Sponsor A's card)
- **Action 1:** Update Contact -> Add tag "sponsor-a"
- **Action 2:** HTTP Request -> POST to sponsor's webhook URL with contact data

### Key Pattern

The core pattern for sponsor lead segmentation:

```
Competition entries are scoped by card

Card A (Sponsor A) --> Entries A --> Tag "sponsor-a"
Card B (Sponsor B) --> Entries B --> Tag "sponsor-b"
Card C (Sponsor C) --> Entries C --> Tag "sponsor-c"

Filter contacts by tag -> Export per-sponsor report
```

### Tips

- **Naming convention:** Use consistent tag formats like `sponsor:acme-corp` or `sponsor:brand-name`. This makes API queries and portal filtering predictable.
- **Multi-sponsor engagement:** A single contact can interact with multiple sponsor cards. They'll get multiple tags. Each sponsor's export will include them -- this is usually what sponsors want (their reach).
- **Extension data:** If you're embedding cards in an event app, set extension data with the sponsor ID. This flows into webhook payloads and can be used for additional segmentation.

Changes here will propagate to all partner hubs using this template. Switch to Preview to see how it renders.

Embed SDK Docs Workflows

Partner Usage

Using template (2)

Eventbase auto-updates

WMT Sports auto-updates

Customised (1)

Fan 360 x Komo own version

Editing impacts 2 hubs

Changes to this template will be reflected in all partner hubs that haven't customised this section. Partners with their own version (1) will not be affected.

Customised Versions

These partners have their own version of this section. Click to compare.

Fan 360 x Komo

View version