Using Custom CRM Integration


This guide explains how to configure and use Sequel's Custom Integration feature to send event and engagement data to your own systems.

Overview

The Custom Integration feature allows you to send event data from Sequel to any HTTP endpoint you control. This is useful when you want to integrate Sequel with systems that don't have pre-built integrations, such as:

  • Custom internal CRMs
  • Data warehouses
  • Analytics platforms
  • Marketing automation tools
  • Custom databases

Key Features

  • Flexible Field Mapping: Map Sequel fields to your own field names
  • Secure Headers: Add authentication tokens and API keys securely
  • Multiple Event Types: Receive data for registrations, event completion, and on-demand viewing
  • Custom Status Values: Map Sequel statuses to your own status values
  • Registration Questions: Map custom registration form responses to your fields
  • Static Fields: Add constant values to every payload

Getting Started

Enabling Custom Integration

  1. Log in to your Sequel Dashboard

    • Navigate to your dashboard at https://admin.sequel.io
  2. Company-Level Setup (One-time)

    • From the main menu, select Integrations
    • Click on Custom Integration
    • Configure your endpoint URL and authentication headers
    • Set up user data and engagement field mappings
  3. Event-Level Configuration (Per Event)

    • Go to your event in the dashboard
    • Navigate to the CRM tab
    • Select Custom Integration
    • Configure event-specific field mappings (registration questions, UTM params, event info)
    • Map status values if needed
    • Add static fields if needed

Prerequisites

  • An HTTP/HTTPS endpoint that can receive POST requests
  • (Optional) Authentication credentials if your endpoint requires them

Configuration

Configuration happens at two levels:

  1. Company-Level (Integrations → Custom Integration): Endpoint, headers, and base field mappings
  2. Event-Level (Event → CRM tab): Event-specific mappings and custom fields

1. Endpoint URL

Where to Configure: Company-Level (Integrations → Custom Integration)

Enter the URL where Sequel should POST the data:

https://your-domain.com/api/webhook/sequel-data

Requirements:

  • Must be a valid HTTPS URL (HTTP allowed for testing)
  • Endpoint must respond with 2xx status code for successful delivery
  • Endpoint should handle POST requests with JSON body

2. Header Mappings (Authentication & Secrets)

Where to Configure: Company-Level (Integrations → Custom Integration)

Headers are used to securely pass authentication credentials and other metadata to your endpoint.

Configuration in Dashboard

In the Header Mappings section, you can add key-value pairs:

Header KeyHeader Value
AuthorizationBearer your_secret_token_here
X-API-Keyyour_api_key_here
Content-Typeapplication/json

Common Use Cases:

  • API Key Authentication

    Key: X-API-Key
    Value: sk_live_abc123xyz789
  • Bearer Token Authentication

    Key: Authorization
    Value: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
  • Basic Authentication

    Key: Authorization
    Value: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
  • Custom Headers

    Key: X-Company-ID
    Value: company_12345

3. User Data Mappings

Where to Configure: Company-Level (Integrations → Custom Integration)

Map basic user information to your field names:

Sequel FieldYour Field NameDescription
first_namefirstNameUser's first name
last_namelastNameUser's last name
full_namefullNameUser's full name
emailemailUser's email address

Example Configuration:

If your system uses contact_first_name instead of firstName:

Sequel Field: first_name
Your Field: contact_first_name

4. Engagement Data Mappings

Where to Configure: Company-Level (Integrations → Custom Integration)

Map event engagement metrics to your field names:

Sequel FieldYour Field NameDescription
statusattendee_statusStatus (Registered, Attended, No Show, etc.)
live_minuteslive_view_timeMinutes watched during live event
on_demand_minutesondemand_view_timeMinutes watched on-demand/archive
live_percent_viewedlive_engagement_pctPercentage of live event watched
on_demand_percent_viewedondemand_engagement_pctPercentage of on-demand watched
question_asked_1question_1First question asked by attendee
poll_question_1poll_1_questionFirst poll question text
poll_answer_1poll_1_answerUser's answer to first poll
cta_name_1cta_1_nameFirst call-to-action name
cta_clicked_1cta_1_urlURL of first CTA that was clicked
resource_name_1resource_1_nameFirst resource name
resource_clicked_1resource_1_urlURL of first resource that was clicked

Poll Mappings (1-10):

Polls are numbered 1 through 10:

  • poll_question_1, poll_answer_1 - First poll
  • poll_question_2, poll_answer_2 - Second poll
  • poll_question_3, poll_answer_3 - Third poll
  • ... up to poll_question_10, poll_answer_10

Question Mappings (1-10):

Questions asked by attendees are numbered:

  • question_asked_1 - First question asked
  • question_asked_2 - Second question asked
  • ... up to question_asked_10

CTA (Call-to-Action) Mappings (1-10):

CTAs are numbered 1 through 10:

  • cta_name_1, cta_clicked_1 - First CTA (name and URL if clicked)
  • cta_name_2, cta_clicked_2 - Second CTA (name and URL if clicked)
  • ... up to cta_name_10, cta_clicked_10

Note: cta_clicked_N contains the actual URL that was clicked (e.g., "https://example.com/demo"), or empty if not clicked.

Resource Mappings (1-10):

Resources are numbered 1 through 10:

  • resource_name_1, resource_clicked_1 - First resource (name and URL if clicked)
  • resource_name_2, resource_clicked_2 - Second resource (name and URL if clicked)
  • ... up to resource_name_10, resource_clicked_10

Note: resource_clicked_N contains the actual URL that was clicked (e.g., "https://example.com/whitepaper.pdf"), or empty if not clicked.

5. Status Value Mappings

Where to Configure: Event-Level (Event → CRM tab → Custom Integration)

Map Sequel's internal status values to your own:

Sequel StatusYour Status Value
Registeredregistered
Attendedattended
No Showno_show
Viewed On Demandwatched_recording

Example:

If your system uses numeric status codes:

Registered → 1
Attended → 2
No Show → 3
Viewed On Demand → 4

6. Custom Field Mappings

Where to Configure: Event-Level (Event → CRM tab → Custom Integration)

Map additional event and registration data to your field names.

Available Fields to Map:

  • Registration Form Questions - Custom questions from your registration form
    • Example: Company Name, Job Title, Phone Number, etc.
  • Event Information
    • Event ID
    • Event Name
    • Event Start Date/Time
  • UTM Parameters (if present in registration URL)
    • utm_source
    • utm_medium
    • utm_campaign
    • utm_term
    • utm_content

Example Mappings:

In the CRM tab, you can map:

Registration Question "Company Name" → company_name
Registration Question "Job Title" → job_title
Event ID → event_id
Event Name → event_name
utm_source → traffic_source
utm_campaign → campaign_name

How to Configure:

  1. Go to your event in Sequel Dashboard
  2. Navigate to the CRM tab
  3. Select Custom Integration
  4. Add field mappings for registration questions and other data

7. Static Mappings

Where to Configure: Event-Level (Event → CRM tab → Custom Integration)

Add constant values that will be included in every payload:

Field NameStatic Value
sourcesequel_webinar
campaign_idQ1_2025_webinar
data_versionv1

Use Cases:

  • Adding source identifiers
  • Including campaign tracking codes
  • Versioning your data format
  • Adding constant metadata

Field Mappings

Available Sequel Fields

User Data Fields

  • first_name - User's first name
  • last_name - User's last name
  • full_name - User's full name
  • email - User's email address

Engagement Fields

  • status - Attendee status
  • live_minutes - Live viewing time (minutes)
  • on_demand_minutes - On-demand/archive viewing time (minutes)
  • live_percent_viewed - Percentage of live event watched
  • on_demand_percent_viewed - Percentage of on-demand content watched

Dynamic Fields (numbered 1-10)

  • poll_question_N - Poll question text (N = 1 to 10)
  • poll_answer_N - User's poll answer (N = 1 to 10)
  • question_asked_N - Question asked by attendee (N = 1 to 10)
  • cta_name_N - Call-to-action name (N = 1 to 10)
  • cta_clicked_N - URL of CTA that was clicked (N = 1 to 10)
  • resource_name_N - Resource name (N = 1 to 10)
  • resource_clicked_N - URL of resource that was clicked (N = 1 to 10)

Event Triggers

Sequel sends data to your custom integration endpoint when specific events occur:

1. New Registration (NewAttendeePreRegistration)

When: A user registers for an event

Frequency: Once per registration

Payload Example:

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "status": "registered",
  "company_name": "Acme Corp",
  "job_title": "Marketing Director",
  "phone": "+1-555-123-4567",
  "event_id": "evt_abc123xyz",
  "event_name": "Q1 Product Launch Webinar",
  "traffic_source": "linkedin",
  "campaign_name": "Q1_2025_launch",
  "utm_medium": "social",
  "data_source": "sequel_integration"
}

Available Data:

  • User information (name, email)
  • Registration form responses (company, job title, phone, etc.)
  • Event information (event ID, event name)
  • UTM parameters (if present)
  • Status: Registered
  • Static fields

Note: Engagement data (minutes watched, polls, etc.) is NOT available at registration time.


2. Event Ended (VirtualStageEventEnded)

When: A live event ends

Frequency: Once per attendee after the event concludes

Payload Example:

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "status": "attended",
  "live_view_time": 45,
  "ondemand_view_time": 0,
  "live_engagement_pct": 90,
  "ondemand_engagement_pct": 0,
  "question_1": "How do I integrate this with my CRM?",
  "question_2": "What's the pricing model?",
  "question_3": "Do you offer training?",
  "poll_1_question": "What topic interests you most?",
  "poll_1_answer": "Product features",
  "poll_2_question": "Would you recommend this to a colleague?",
  "poll_2_answer": "Yes",
  "cta_1_name": "Download Whitepaper",
  "cta_1_clicked": "https://example.com/whitepaper",
  "cta_2_name": "Schedule Demo",
  "cta_2_clicked": "",
  "resource_1_name": "Product_Deck.pdf",
  "resource_1_clicked": "https://cdn.example.com/product-deck.pdf",
  "resource_2_name": "Case_Study.pdf",
  "resource_2_clicked": "",
  "company_name": "Acme Corp",
  "job_title": "Marketing Director",
  "phone": "+1-555-123-4567",
  "event_id": "evt_abc123xyz",
  "event_name": "Q1 Product Launch Webinar",
  "traffic_source": "linkedin",
  "campaign_name": "Q1_2025_launch",
  "data_source": "sequel_integration"
}

Available Data:

  • User information (name, email)
  • Registration form responses (company, job title, phone, etc.)
  • Event information (event ID, event name)
  • UTM parameters (if captured at registration)
  • Full engagement data:
    • Live viewing time
    • On-demand viewing time
    • Live engagement percentage
    • On-demand engagement percentage
    • Poll responses (up to 10 polls)
    • Questions asked (up to 10 questions)
    • CTA interactions (up to 10 CTAs)
    • Resource interactions (up to 10 resources)
  • Status: Attended or No Show
  • Static fields

3. On-Demand Event Viewed (VirtualStageEventOnDemand)

When: A user watches a recording (on-demand/archive)

Frequency: Every 24 hours once per attendee if an on-demand view is detected

Payload Example:

{
  "email": "[email protected]",
  "firstName": "Jane",
  "lastName": "Smith",
  "fullName": "Jane Smith",
  "status": "watched_recording",
  "live_view_time": 0,
  "ondemand_view_time": 30,
  "live_engagement_pct": 0,
  "ondemand_engagement_pct": 60,
  "question_1": "Is there an API available?",
  "cta_1_name": "Download Whitepaper",
  "cta_1_clicked": "https://example.com/whitepaper",
  "resource_1_name": "Product_Deck.pdf",
  "resource_1_clicked": "https://cdn.example.com/product-deck.pdf",
  "company_name": "Beta Inc",
  "job_title": "Sales Manager",
  "phone": "+1-555-987-6543",
  "event_id": "evt_abc123xyz",
  "event_name": "Q1 Product Launch Webinar",
  "traffic_source": "email",
  "campaign_name": "Q1_2025_launch",
  "data_source": "sequel_integration"
}

Available Data:

  • User information (name, email)
  • Registration form responses (company, job title, phone, etc.)
  • Event information (event ID, event name)
  • UTM parameters (if captured at registration)
  • Engagement data:
    • On-demand viewing time
    • On-demand engagement percentage
    • Questions asked (if enabled for on-demand)
    • CTA interactions
    • Resource interactions
  • Status: Viewed On Demand (or your custom value)
  • Static fields

Note: Poll responses may not be available for on-demand viewers depending on your event settings.


Payload Examples

Complete Payload Structure

When Sequel sends data to your endpoint, the HTTP request looks like this:

HTTP Request:

POST /api/webhook/sequel-data HTTP/1.1
Host: your-domain.com
Content-Type: application/json
Authorization: Bearer your_secret_token_here
X-API-Key: your_api_key_here
Content-Length: 456

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "fullName": "John Doe",
  "status": "attended",
  "view_time_minutes": 45,
  "engagement_percentage": 90,
  "company_name": "Acme Corp",
  "source": "sequel_webinar"
}

Minimal Configuration Example

Dashboard Configuration:

User Data Mappings:

email → email
full_name → name

Engagement Mappings:

status → status

Resulting Payload (New Registration):

{
  "email": "[email protected]",
  "name": "John Doe",
  "status": "registered"
}

Resulting Payload (Event Ended):

{
  "email": "[email protected]",
  "name": "John Doe",
  "status": "attended"
}

Advanced Configuration Example

Dashboard Configuration:

Headers:

Authorization: Bearer sk_live_abc123
X-Company-ID: company_789

User Data Mappings:

first_name → contact_first_name
last_name → contact_last_name
email → contact_email

Engagement Mappings:

status → attendee_status
minutes_watched → viewing_minutes
percentage_view_time → engagement_score
poll_question_1 → survey_question_1
poll_answer_1 → survey_answer_1
questions_asked → qna_questions

Status Value Mappings:

Registered → STATUS_REGISTERED
Attended → STATUS_ATTENDED
No Show → STATUS_NO_SHOW

Registration Field Mappings:

question_company_name → company
question_job_title → title

Static Mappings:

data_source → sequel_integration
version → 2.0

Resulting Payload (Event Ended):

{
  "contact_first_name": "John",
  "contact_last_name": "Doe",
  "contact_email": "[email protected]",
  "attendee_status": "STATUS_ATTENDED",
  "viewing_minutes": 42,
  "engagement_score": 84,
  "survey_question_1": "What's your biggest challenge?",
  "survey_answer_1": "Lead generation",
  "qna_questions": 2,
  "company": "Acme Corp",
  "title": "VP Marketing",
  "data_source": "sequel_integration",
  "version": "2.0"
}

How Data is Sent

Delivery Mechanism

  1. Queue-Based Processing

    • Data is added to a FIFO queue for reliable delivery
    • Guarantees order and prevents duplicates
    • Automatic retries on failures
  2. One Record Per User

    • Each payload contains data for ONE user
    • For 100 attendees, you'll receive 100 separate POST requests
  3. Batching

    • Requests are sent sequentially
    • Small delays between requests to prevent overwhelming your endpoint

HTTP Request Format

POST {your_endpoint_url}
{your_custom_headers}
Content-Type: application/json

{your_mapped_payload}

Expected Response

Your endpoint should respond with:

  • Success: HTTP status code 2xx (200, 201, 204)
  • Failure: Any non-2xx status code triggers a retry

Example Successful Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "id": "record_12345"
}

Retry Logic

  • Failed requests are automatically retried
  • Exponential backoff between retries
  • Multiple attempts over several hours
  • After max retries, the request is logged as failed

Troubleshooting

Common Issues

1. Not Receiving Any Data

Possible Causes:

  • Custom integration not enabled in dashboard
  • Endpoint URL is incorrect or unreachable
  • Firewall blocking Sequel's IP addresses
  • Endpoint requires HTTPS but HTTP provided

Solutions:

  • Verify integration is enabled and saved
  • Test endpoint with a tool like Postman
  • Check firewall and security group settings
  • Ensure using HTTPS for production endpoints

2. Authentication Errors

Symptoms:

  • Receiving 401 or 403 responses

Solutions:

  • Verify header keys and values are correct
  • Check for typos in tokens/keys
  • Ensure tokens haven't expired
  • Test authentication separately

3. Missing Fields in Payload

Possible Causes:

  • Field not mapped in dashboard configuration
  • Data not available for that event type
  • User didn't provide that information

Solutions:

  • Review field mappings in dashboard
  • Check which fields are available for each event type
  • Verify registration form includes required questions

4. Incorrect Field Values

Possible Causes:

  • Status value mapping not configured
  • Field name mismatch
  • Data type expectations not met

Solutions:

  • Configure status value mappings if needed
  • Double-check field name spelling
  • Handle missing/null values in your endpoint

Testing Your Integration

1. Test Endpoint

Create a test endpoint that logs all incoming requests:

// Example Node.js/Express endpoint
app.post('/api/webhook/sequel-data', (req, res) => {
  console.log('Headers:', req.headers);
  console.log('Body:', req.body);
  res.status(200).json({ success: true });
});

2. Test Event

  1. Create a test event in Sequel
  2. Register yourself as an attendee
  3. Check if registration webhook is received
  4. Join and leave the event
  5. Check if event ended webhook is received

3. Use Webhook Testing Tools

4. Check Logs

  • Monitor your endpoint logs for incoming requests
  • Check for error messages
  • Verify payload structure matches expectations

Support

If you continue to experience issues:

  1. Check Dashboard Logs

    • Go to Integrations → Custom Integration
    • View recent webhook attempts and responses
  2. Contact Support

    • Email: [email protected]
    • Provide:
      • Event ID
      • Endpoint URL (without sensitive tokens)
      • Error messages or response codes
      • Time of failed attempts

Best Practices

Security

  • Always use HTTPS for production endpoints
  • Rotate tokens regularly and update in dashboard
  • Validate requests in your endpoint (verify headers, check signatures)
  • Don't log sensitive data (tokens, API keys)

Performance

  • Respond quickly (within 5 seconds)
  • Process asynchronously if you need to do heavy processing
  • Return 200 immediately and process in background
  • Handle high volume (large events can generate hundreds of webhooks)

Reliability

  • Implement idempotency (handle duplicate requests gracefully)
  • Store raw payloads before processing (for debugging)
  • Monitor endpoint health and set up alerts
  • Have a retry strategy in your endpoint

Data Quality

  • Validate incoming data structure and types
  • Handle missing fields gracefully (use defaults)
  • Log validation errors for debugging
  • Normalize data before storing

Summary

Custom Integration provides a flexible way to send Sequel event data to any system:

Configure once in the Sequel dashboard ✅ Map fields to match your data structure ✅ Secure headers for authentication ✅ Automatic delivery when events occur ✅ Reliable queue-based processing with retries

For questions or support, contact [email protected] or visit our help center.