n8n Integration
The OnboardingHub community node for n8n gives you native access to contacts, organizations, enrollments, and guides -- plus real-time triggers for enrollment events, CES scores, file uploads, and more. No raw HTTP requests required.
During the launch phase the node is distributed as a community package that you install locally into your n8n instance.
Installing the community node
The OnboardingHub node is distributed as an npm package. During the launch phase, install it with one of the methods below.
Self-hosted n8n
cd ~/.n8n
npm install @onboardinghub/n8n-nodes-onboardinghub
Restart n8n after installation. The OnboardingHub and OnboardingHub Trigger nodes will appear in the node picker.
n8n Cloud
- Go to Settings > Community Nodes
- Click Install a community node
- Enter the package name:
@onboardinghub/n8n-nodes-onboardinghub - Click Install
The nodes are available immediately -- no restart required.
Docker
If you run n8n in Docker, add the package to a custom Dockerfile:
FROM n8nio/n8n:latest
RUN cd /usr/local/lib/node_modules/n8n && \
npm install @onboardinghub/n8n-nodes-onboardinghub
Verifying the installation
After restarting, open the node picker and search for OnboardingHub. You should see two nodes:
- OnboardingHub -- perform CRUD operations on contacts, organizations, enrollments, and guides
- OnboardingHub Trigger -- start workflows when events happen in your workspace
Connecting to OnboardingHub
The community node uses OAuth 2.0 to connect to your workspace. n8n handles the entire authorization flow for you.
- Add an OnboardingHub or OnboardingHub Trigger node to your workflow
- Click the Credential dropdown and select Create New
- Click Connect my account -- a browser window opens to OnboardingHub
- Sign in to OnboardingHub, select your workspace, and approve the requested permissions
- The credential is saved automatically in n8n
That's it. The node manages token refresh behind the scenes, so your workflows stay connected without manual intervention.
Scopes
The following scopes are requested during authorization. They control which operations your workflows can perform.
| Scope | Grants access to |
|---|---|
contacts:read |
List, get, and search contacts |
contacts:write |
Create, update, and delete contacts |
organisations:read |
List and get organizations |
organisations:write |
Create, update, and delete organizations |
enrollments:read |
List and get enrollments |
enrollments:write |
Create, update, and delete enrollments |
guides:read |
List and get published guides |
webhooks:manage |
Manage webhook endpoints (used internally by the trigger node) |
OnboardingHub node -- operations
The main OnboardingHub node lets you perform CRUD operations on four resources. Select a Resource and an Operation in the node editor.
Contacts
Manage the people you are onboarding.
| Operation | Description |
|---|---|
| Create | Create a new contact. Fields: email (required), first name, last name, external ID, organization, metadata. |
| Get | Retrieve a single contact by ID. |
| Get Many | List contacts with optional filters: email, organization. Supports pagination. |
| Update | Update a contact's fields. Only include fields you want to change. |
| Delete | Soft-delete a contact. |
| Search | Search contacts by name or email. |
Organizations
Group contacts into organizations.
| Operation | Description |
|---|---|
| Create | Create an organization. Fields: name (required), domain, metadata. |
| Get | Retrieve a single organization by ID. |
| Get Many | List organizations with optional filters: name, domain. Supports pagination. |
| Update | Update an organization's fields. |
| Delete | Permanently delete an organization. |
Enrollments
Assign contacts to guides and track their progress.
| Operation | Description |
|---|---|
| Create | Enroll a contact in a guide. Fields: contact ID (required), guide ID (required), metadata. |
| Get | Retrieve an enrollment with full progress details, CES score, and nested contact/guide data. |
| Get Many | List enrollments with optional filters: contact, guide, organization, status (invited, in_progress, completed, expired). |
| Update | Update enrollment fields (e.g. status, metadata). |
| Delete | Permanently delete an enrollment. |
Guides
Read-only access to published guides and their structure.
| Operation | Description |
|---|---|
| Get | Retrieve a guide with nested sections and steps. |
| Get Many | List all published guides. Supports pagination. |
OnboardingHub Trigger node -- events
The OnboardingHub Trigger node starts a workflow whenever a selected event occurs in your workspace. Behind the scenes the trigger node registers a webhook endpoint via the API and removes it when the workflow is deactivated. Your n8n credential needs the webhooks:manage scope.
Available trigger events
| Event | Fires when |
|---|---|
enrollment.created |
A contact is enrolled in a guide |
enrollment.started |
A contact begins a guide (status changes to in_progress) |
enrollment.completed |
A contact finishes all steps (status changes to completed) |
enrollment.expired |
An enrollment expires |
guide.viewed |
A contact views a guide |
step.completed |
A contact completes a step |
section.completed |
A contact completes all steps in a section |
file.uploaded |
A contact uploads a file in a file upload step |
ces.submitted |
A contact submits a Customer Effort Score |
You can subscribe to one or more events per trigger node.
Trigger payload
Every trigger execution receives the full webhook payload. See the Webhooks documentation for the detailed JSON structure. Key fields available in expressions:
{{ $json.event }}-- the event name (e.g.enrollment.completed){{ $json.timestamp }}-- ISO 8601 timestamp{{ $json.data.id }}-- the enrollment or resource ID{{ $json.data.contact.email }}-- the contact's email{{ $json.data.contact.first_name }}-- the contact's first name{{ $json.data.guide.name }}-- the guide name{{ $json.data.status }}-- enrollment status{{ $json.data.progress_percent }}-- completion percentage
Example workflows
1. Enroll new CRM contacts automatically
Trigger: a webhook or schedule from your CRM (e.g. HubSpot, Salesforce)
| # | Node | Configuration |
|---|---|---|
| 1 | HTTP Request or CRM trigger | Fires when a deal closes or a contact is created |
| 2 | OnboardingHub > Contact > Create | Create a contact with the email, first name, and last name from the CRM |
| 3 | OnboardingHub > Enrollment > Create | Enroll the new contact in your Getting Started guide |
| 4 | Slack | Post a message: "Enrolled {{ $json.data.contact.email }} in onboarding" |
2. Notify Slack when onboarding completes
Trigger: OnboardingHub Trigger (enrollment.completed)
| # | Node | Configuration |
|---|---|---|
| 1 | OnboardingHub Trigger | Event: enrollment.completed |
| 2 | Slack | Channel: #customer-success, message: "{{ $json.data.contact.firstname }} {{ $json.data.contact.lastname }} completed {{ $json.data.guide.name }}" |
3. Follow up on low CES scores
Trigger: OnboardingHub Trigger (ces.submitted)
| # | Node | Configuration |
|---|---|---|
| 1 | OnboardingHub Trigger | Event: ces.submitted |
| 2 | IF | {{ $json.data.ces_score }} is less than 3 |
| 3 | Slack | Alert: "Low CES ({{ $json.data.ces_score }}) from {{ $json.data.contact.email }} on {{ $json.data.guide.name }}" |
| 4 | OnboardingHub > Contact > Get | Fetch full contact details |
| 5 | Linear / Jira / Asana | Create a follow-up task for the CS team |
4. Sync enrollment progress to Google Sheets
Trigger: OnboardingHub Trigger (enrollment.created, enrollment.started, enrollment.completed)
| # | Node | Configuration |
|---|---|---|
| 1 | OnboardingHub Trigger | Events: enrollment.created, enrollment.started, enrollment.completed |
| 2 | Google Sheets | Append row: contact email, guide name, event type, timestamp |
5. Re-enroll expired contacts
Trigger: OnboardingHub Trigger (enrollment.expired)
| # | Node | Configuration |
|---|---|---|
| 1 | OnboardingHub Trigger | Event: enrollment.expired |
| 2 | OnboardingHub > Enrollment > Create | Re-enroll the same contact in the same guide |
| 3 | Gmail / Postmark | Send reminder email: "We noticed you haven't finished {{ $json.data.guide.name }}. We've re-enrolled you so you can pick up where you left off." |
6. Bulk-enroll contacts from a spreadsheet
Trigger: Manual or scheduled
| # | Node | Configuration |
|---|---|---|
| 1 | Google Sheets | Read rows from an "Onboarding Queue" sheet |
| 2 | OnboardingHub > Contact > Create | Create or look up each contact by email |
| 3 | OnboardingHub > Enrollment > Create | Enroll each contact in the specified guide |
| 4 | Google Sheets | Mark rows as processed |
Automation ideas
| Trigger event | Automation |
|---|---|
enrollment.created |
Send a welcome Slack DM or email to the new enrollee |
enrollment.completed |
Notify the customer success team, update CRM status |
enrollment.expired |
Send a reminder email, re-enroll the contact |
ces.submitted |
Alert on low scores, log all scores to a spreadsheet |
file.uploaded |
Copy the file metadata to a project management tool |
step.completed |
Update a progress tracker in Google Sheets |
Fallback: HTTP Request node
If the community node does not cover your use case, you can call the OnboardingHub API directly using n8n's built-in HTTP Request node with your OAuth credential.
Method: GET
URL: https://onboarding-hub.com/api/v1/contacts
Authentication: Predefined Credential Type > OnboardingHub OAuth2 API
This approach works for any endpoint documented in the interactive API reference. You can also use the Webhook node with OnboardingHub's outbound webhooks for a code-free trigger setup -- see Webhooks for details.
Troubleshooting
"Unknown node type" after installation
Make sure you restarted n8n after installing the package. If you installed via Docker, rebuild the image and recreate the container.
OAuth connection fails
- Confirm your n8n instance is accessible over HTTPS (OnboardingHub requires HTTPS redirect URIs).
- If you see a redirect URI mismatch error, verify the callback URL displayed in n8n's credential form matches the one registered for the OnboardingHub integration.
- Check your browser's developer console for any blocked pop-ups during the OAuth flow.
Trigger node does not fire
- The trigger node requires the
webhooks:managescope. Verify your OAuth credential includes this scope. - Confirm the workflow is active (toggle in the top right of the n8n editor).
- Check Integrations > Webhooks in OnboardingHub to verify the endpoint was registered and is enabled.
Rate limiting
The OnboardingHub API applies rate limits to all requests (60/minute, 500/hour per token). If your workflow processes large batches, add a Wait node between iterations or use pagination to avoid hitting limits. See the API Overview for rate limit headers.
Next steps
- Webhooks -- event types, payload format, and signature verification
- API reference -- full REST API documentation
- Zapier integration -- connect OnboardingHub to Zapier