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

Log in to your Sequel Dashboard
- Navigate to your dashboard at https://admin.sequel.io
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
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:

Company-Level (Integrations → Custom Integration): Endpoint, headers, and base field mappings
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 Key	Header Value
`Authorization`	`Bearer your_secret_token_here`
`X-API-Key`	`your_api_key_here`
`Content-Type`	`application/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 Field	Your Field Name	Description
`first_name`	`firstName`	User's first name
`last_name`	`lastName`	User's last name
`full_name`	`fullName`	User's full name
`email`	`email`	User'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 Field	Your Field Name	Description
`status`	`attendee_status`	Status (Registered, Attended, No Show, etc.)
`live_minutes`	`live_view_time`	Minutes watched during live event
`on_demand_minutes`	`ondemand_view_time`	Minutes watched on-demand/archive
`live_percent_viewed`	`live_engagement_pct`	Percentage of live event watched
`on_demand_percent_viewed`	`ondemand_engagement_pct`	Percentage of on-demand watched
`question_asked_1`	`question_1`	First question asked by attendee
`poll_question_1`	`poll_1_question`	First poll question text
`poll_answer_1`	`poll_1_answer`	User's answer to first poll
`cta_name_1`	`cta_1_name`	First call-to-action name
`cta_clicked_1`	`cta_1_url`	URL of first CTA that was clicked
`resource_name_1`	`resource_1_name`	First resource name
`resource_clicked_1`	`resource_1_url`	URL 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 Status	Your Status Value
`Registered`	`registered`
`Attended`	`attended`
`No Show`	`no_show`
`Viewed On Demand`	`watched_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:

Go to your event in Sequel Dashboard
Navigate to the CRM tab
Select Custom Integration
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 Name	Static Value
`source`	`sequel_webinar`
`campaign_id`	`Q1_2025_webinar`
`data_version`	`v1`

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": "john.doe@example.com",
  "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": "john.doe@example.com",
  "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": "jane.smith@example.com",
  "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": "john.doe@example.com",
  "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": "user@example.com",
  "name": "John Doe",
  "status": "registered"
}

Resulting Payload (Event Ended):

{
  "email": "user@example.com",
  "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": "john.doe@example.com",
  "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

Queue-Based Processing
- Data is added to a FIFO queue for reliable delivery
- Guarantees order and prevents duplicates
- Automatic retries on failures
One Record Per User
- Each payload contains data for ONE user
- For 100 attendees, you'll receive 100 separate POST requests
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

Create a test event in Sequel
Register yourself as an attendee
Check if registration webhook is received
Join and leave the event
Check if event ended webhook is received

3. Use Webhook Testing Tools

RequestBin: https://requestbin.com/
Webhook.site: https://webhook.site/
ngrok: For testing local endpoints

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:

Check Dashboard Logs
- Go to Integrations → Custom Integration
- View recent webhook attempts and responses
Contact Support
- Email: support@sequel.io
- 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

For questions or support, contact support@sequel.io or visit our help center.