n8n Integration Guide

The n8n integration lets you send Bearconnect LinkedIn outreach events directly to an n8n webhook trigger, which starts n8n workflows. Whenever a lead accepts a connection, a message is sent, or another tracked event occurs, Bearconnect sends a JSON payload to your configured n8n webhook URL. This is ideal for building complex automation workflows with conditional logic, self-hosted data processing, and multi-step lead routing - all without writing code.

What You Need
Production URL vs Test URL
Connecting n8n to Bearconnect
After Connecting
Connecting n8n to a Campaign
Exporting Leads via n8n
Payload Format
Working with Payloads in n8n
Testing Your Connection
Managing Your n8n Integration
Use Cases
Troubleshooting

Quick Start

Already familiar with n8n? Here is the fastest path:

In n8n: Create a workflow with a Webhook trigger node. Switch to the Production tab and copy the Production URL.
Activate the workflow (inactive workflows return 404 on the Production URL).
In Bearconnect: Go to Integrations > n8n > Connect. Paste the Production URL, configure authentication if needed, select events, click Connect.
In Bearconnect: Click Test Connection to verify the webhook is reachable.
In Bearconnect: Open a campaign > Integrations tab > Connect Integration > select your n8n integration and enable events.

Common mistake: Using the Test URL (/webhook-test/) instead of the Production URL (/webhook/). Test URLs only work while the workflow is open in the n8n editor. Always use the Production URL for Bearconnect.

What You Need

A Bearconnect account with an active subscription.
An n8n instance (cloud or self-hosted) accessible over HTTPS.
An n8n workflow with a Webhook trigger node configured.

Production URL vs Test URL

This is the most common source of issues with the n8n integration. n8n provides two webhook URL variants for every Webhook trigger node:

Variant	URL Pattern	When It Works
Test URL	`https://your-n8n.com/webhook-test/{uuid}`	Only while the workflow is open in the n8n editor.
Production URL	`https://your-n8n.com/webhook/{uuid}`	Whenever the workflow is enabled (active).

Bearconnect only accepts Production URLs. If you paste a test URL, Bearconnect will show the following error:

"This appears to be an n8n TEST webhook URL (/webhook-test/). Please use the Production URL (/webhook/) instead."

How to Get the Production URL

Open your workflow in the n8n editor.
Click on the Webhook trigger node.
In the node settings panel, switch to the Production tab.
Copy the Production URL.

Connecting n8n to Bearconnect

Go to Integrations in the left sidebar of your Bearconnect dashboard.
Find n8n in the Available Integrations section and click Connect.
A dialog opens with the following fields:

Required Fields

Field	Description
Webhook URL	Your n8n Production webhook URL (must start with `https://` and must not contain `/webhook-test/`).
Name	A label to identify this integration (e.g., "n8n - Lead Processing").

Authentication

Choose how Bearconnect authenticates with your n8n Webhook node. Credentials are stored encrypted in Bearconnect.

Method	Description
None	No authentication. This is the default and is suitable for trusted networks.
Header Auth	Bearconnect sends an `X-N8N-Auth: <token>` header with every request. You must configure the same token in your n8n Webhook node's authentication settings.
Basic Auth	Bearconnect sends an `Authorization: Basic base64(user:pass)` header with every request. You must configure the same username and password in your n8n Webhook node's authentication settings.

If you choose Header Auth, enter the auth token in the field that appears.

If you choose Basic Auth, enter the username and password in the fields that appear.

Event Selection

Choose which event types this integration is allowed to handle:

Category	Events
Connection Events	Connection Request Sent, Connection Accepted
Message Events	Message Sent, Message Replied

You can:

Click All to select every event.
Click None to clear the selection.
Expand a category to select individual events.
Use the category checkbox to toggle all events within that category.

Advanced Settings (Optional)

Click Advanced Settings to reveal additional options:

Setting	Default	Range	Description
Custom Headers	None	-	Add custom HTTP headers to every request sent to n8n (e.g., `X-Source: bearconnect`).
Timeout (ms)	30000	5000–60000	How long to wait for your n8n instance to respond before marking the delivery as failed.

Click Connect.

After Connecting

Your n8n integration now appears in the Connected Integrations section. Click on it to open the detail panel, which shows:

Webhook URL

Your configured n8n Production webhook URL is displayed and can be copied with the copy button.

Status & Delivery Statistics

Status - Active or Error.
Delivered - Total number of successful deliveries.
Failed - Total number of failed deliveries.
Last Delivery - Timestamp of the most recent delivery.

If there is a recent error, the error message is displayed in red.

Allowed Events

A read-only list showing which event types this integration is configured to handle, organized by category.

Connection Details

When the integration was created.
Provider type (n8n).
Integration ID.
Last updated timestamp.

Connecting n8n to a Campaign

To receive events from a specific campaign, you must map the n8n integration to that campaign.

Open a campaign from your dashboard.
Go to the Integrations tab.
Click Connect Integration.
Select your n8n integration from the dropdown.
Choose which events to enable for this campaign (only events that are in the integration's allowed events list appear here).
Click Connect.

Managing the Mapping

On the campaign's Integrations tab:

Toggle switch - Pause or resume event forwarding.
Settings icon - Change which events are enabled for this campaign.
Trash icon - Remove the mapping (the n8n integration itself is not deleted).

Exporting Leads via n8n

You can manually export a lead to your n8n workflow.

Go to the Leads page.
Find the lead you want to export and click the three-dot action menu (⋮) on that row.
Click Export.
Select your n8n integration from the dropdown.
Click Export.

The lead data is sent immediately as a JSON payload to your n8n webhook URL.

Payload Format

Every delivery to n8n is an HTTP POST request with a JSON body. This is the universal payload format used by Custom Webhooks, Zapier, Make, and n8n. All providers receive the exact same structure.

Event Payload

{
    "event": "connection_request_accepted",
    "timestamp": "2026-02-13T10:30:00.000Z",
    "data": {
        "lead": {
            "id": "65abc123def4567890ghij01",
            "firstName": "Jane",
            "lastName": "Smith",
            "email": "jane.smith@example.com",
            "phone": "+1-555-0123",
            "profileUrl": "https://www.linkedin.com/in/janesmith",
            "profileHeadline": "VP of Sales at Acme Corp",
            "profileImageUrl": "https://media.licdn.com/...",
            "position": "VP of Sales",
            "companyName": "Acme Corp",
            "location": "San Francisco, CA",
            "website": "https://acme.com",
            "education": "Stanford University",
            "publicIdentifier": "janesmith",
            "connectionCount": 500,
            "followerCount": 1200,
            "isPremium": true,
            "memberUrn": "urn:li:member:123456789",
            "stage": "connected",
            "createdAt": "2026-01-15T08:00:00.000Z"
        },
        "campaign": {
            "id": "65abc123def4567890ghij02",
            "name": "Q1 Outreach",
            "status": "running"
        },
        "linkedInAccount": {
            "id": "65abc123def4567890ghij03",
            "name": "Sales Team Account",
            "email": "john.smith@example.com"
        }
    },
    "metadata": {
        "eventId": "evt_abc123def456",
        "userId": "65abc123def4567890ghij04",
        "integrationId": "65abc123def4567890ghij05"
    }
}

Field Availability (Nullable Fields)

Not all lead fields are guaranteed to have a value. Only id and firstName are always present. All other lead fields may be null or absent depending on what data is available on the LinkedIn profile.

Field	Always Present?	Notes
`data.lead.id`	Yes	Bearconnect internal lead ID.
`data.lead.firstName`	Yes	Always available from LinkedIn.
`data.lead.lastName`	No	May be `null` if not available on LinkedIn.
`data.lead.email`	No	Only present if the lead's email has been found or enriched.
`data.lead.phone`	No	Only present if the lead's phone has been found or enriched.
`data.lead.profileUrl`	No	May be `null` in rare cases.
`data.lead.profileHeadline`	No	May be `null` if the lead has no LinkedIn headline.
`data.lead.profileImageUrl`	No	May be `null` if the lead has no profile photo.
`data.lead.position`	No	May be `null` if no current position is listed.
`data.lead.companyName`	No	May be `null` if no company is listed.
`data.lead.location`	No	May be `null` if no location is listed.
`data.lead.website`	No	May be `null` if no website is listed.
`data.lead.education`	No	May be `null` if no education is listed.
`data.lead.publicIdentifier`	No	The LinkedIn vanity URL slug. May be `null`.
`data.lead.connectionCount`	No	Defaults to `0` if not available.
`data.lead.followerCount`	No	May be `null` if not available.
`data.lead.isPremium`	No	Defaults to `false` if not available.
`data.lead.memberUrn`	No	LinkedIn member URN. May be `null`.
`data.lead.stage`	No	Bearconnect lead stage. May be `null`.
`data.lead.createdAt`	No	ISO timestamp. May be `null`.
`data.campaign`	No	May be absent if the event is not campaign-specific.
`data.linkedInAccount`	No	May be absent if no LinkedIn account is associated.
`data.linkedInAccount.email`	Yes (if present)	Login email of the LinkedIn account used for outreach.

Tip: In n8n, use the IF node or expressions like {{ $json.body.data.lead.email ?? "no-email" }} to handle nullable fields. This prevents workflow errors when a field is missing.

Lead Export Payload

When you manually export a lead, the payload follows the same structure. The event field is set to lead_added_to_campaign.

HTTP Headers

Every request to n8n includes:

Header	Value
`Content-Type`	`application/json`
`User-Agent`	`Bearconnect/1.0`
`X-N8N-Auth`	Your auth token (only if Header Auth is configured).
`Authorization`	`Basic base64(user:pass)` (only if Basic Auth is configured).
Custom headers	Any headers you configured in Advanced Settings.

Working with Payloads in n8n

Accessing Fields with n8n Expressions

In any n8n node after the Webhook trigger, the incoming data is nested inside $json.body. You can reference fields using expressions:

Expression	Returns
`{{ $json.body.event }}`	The event type (e.g., `connection_request_accepted`).
`{{ $json.body.timestamp }}`	The ISO 8601 timestamp of the event.
`{{ $json.body.data.lead.firstName }}`	The lead's first name.
`{{ $json.body.data.lead.lastName }}`	The lead's last name.
`{{ $json.body.data.lead.email }}`	The lead's email address.
`{{ $json.body.data.lead.profileUrl }}`	The lead's LinkedIn profile URL.
`{{ $json.body.data.lead.companyName }}`	The lead's company name.
`{{ $json.body.data.lead.location }}`	The lead's location.
`{{ $json.body.data.campaign.name }}`	The campaign name.
`{{ $json.body.data.linkedInAccount.email }}`	The login email of the LinkedIn account used.
`{{ $json.body.metadata.eventId }}`	A unique event ID for deduplication.

Routing Events with Switch or If Nodes

Use {{ $json.body.event }} in a Switch node or If node to route different event types to different branches of your workflow. For example, you can send connection acceptances to your CRM and message replies to Slack.

Deduplication

Use {{ $json.body.metadata.eventId }} to detect and skip duplicate deliveries in your n8n workflow. This is useful if retries cause the same event to arrive more than once.

Testing Your Connection

You can send a test request to verify your n8n webhook is reachable and responding correctly.

Go to Integrations in the left sidebar.
Click on your n8n integration to open the detail panel.
Click Test Connection.
If successful, you will see "Test successful" with the HTTP status code (e.g., 200).
If it fails, the error message will indicate the problem (timeout, connection refused, non-2xx status code, etc.).

The test sends a sample payload to your n8n webhook URL. Your n8n Webhook node should respond with a 2xx status code (200, 201, 202, etc.) to indicate success.

Important: Make sure your n8n workflow is active (enabled) before testing. If the workflow is inactive, the Production URL will return a 404 error.

Managing Your n8n Integration

Editing the Integration

To change the name, URL, authentication, events, or other settings:

Go to Integrations in the left sidebar.
Click on the n8n integration you want to edit.
Make your changes in the detail panel.
Save.

Deleting the Integration

Go to Integrations in the left sidebar.
Click on the n8n integration you want to delete.
Click Delete and confirm.

When you delete an n8n integration:

All campaign mappings using it are removed.
Event forwarding stops immediately.
Delivery history is no longer tracked.

Use Cases

Complex Lead Routing with Conditional Logic

Build workflows that route leads based on company name, location, or job title. For example, send enterprise leads (companyName matches a target list) to your sales team in Slack, and SMB leads to a nurture sequence in your email tool.

Self-Hosted Data Processing (Data Privacy)

If you run n8n on your own infrastructure, lead data is sent directly from Bearconnect to your servers. This means:

Data residency - Lead data stays within your network once received. No third-party automation platform stores it.
Compliance - Ideal for teams subject to GDPR, SOC 2, or other data handling requirements.
Full control - You control data retention, logging, and access policies on your own servers.

To set this up, ensure your self-hosted n8n instance is accessible over HTTPS with a valid TLS certificate (see Troubleshooting for details). Bearconnect also supports Header Auth and Basic Auth to secure the webhook endpoint.

Multi-Step Enrichment and CRM Sync

Create a workflow that triggers when a connection is accepted, enriches the lead with a third-party API (e.g., Clearbit, Apollo), creates a contact in your CRM (e.g., HubSpot, Salesforce), and notifies your team in Slack - all in a single automated flow.

Filtering and Routing by Lead Attributes

Use n8n If or Switch nodes to filter events based on {{ $json.body.data.lead.companyName }} or {{ $json.body.data.lead.location }} and route them to different downstream systems or team channels.

Troubleshooting

"n8n webhook not found (404)"

Check that your workflow is active - In n8n, open the workflow and make sure the toggle in the top-right corner is set to Active. An inactive workflow does not listen on the Production URL.
Check that you are using the Production URL - The URL must contain /webhook/, not /webhook-test/. Test URLs only work while the workflow is open in the editor.

"n8n webhook authentication failed (401)"

Check the auth token or credentials - The token (for Header Auth) or username/password (for Basic Auth) configured in Bearconnect must exactly match what is configured in the n8n Webhook node's authentication settings.
Check the auth method - Make sure both Bearconnect and the n8n Webhook node are using the same authentication method (None, Header Auth, or Basic Auth).

"n8n webhook URL must use HTTPS"

Bearconnect requires all webhook URLs to use HTTPS. If you are running a self-hosted n8n instance:

Set up a reverse proxy (e.g., Nginx, Caddy, Traefik) in front of n8n with a valid TLS certificate.
Use a service like Let's Encrypt to obtain a free certificate.
Ensure the URL you paste into Bearconnect starts with https://.

"This appears to be an n8n TEST webhook URL"

You pasted a URL containing /webhook-test/. Bearconnect requires the Production URL. To fix this:

Open your workflow in the n8n editor.
Click on the Webhook trigger node.
Switch to the Production tab.
Copy the Production URL (it will contain /webhook/ instead of /webhook-test/).
Paste the Production URL into Bearconnect.

Events not arriving in n8n

Check that the workflow is active - Inactive workflows do not receive events on the Production URL.
Check campaign mapping - Open the campaign's Integrations tab and verify the n8n integration is connected and the toggle is enabled.
Check event selection - Verify the events you expect are enabled both on the integration (in Integrations settings) and on the campaign mapping.
Check authentication - If auth credentials do not match, n8n will reject the request silently or return a 401.
Check delivery status - Open the n8n integration detail panel in Bearconnect and look for error messages or failed delivery counts.

Deliveries showing as "failed" with retries

Bearconnect automatically retries failed deliveries with exponential backoff. If all retries fail, the delivery is marked as permanently failed and the error count increases on the integration's status. Common causes:

n8n instance temporarily unavailable.
Workflow was deactivated between retries.
n8n returning non-2xx responses due to workflow errors.

Check the error message in the integration detail panel for specific details.

"No connected integrations found" when trying to export a lead

This means you have not connected any integrations yet. Go to Integrations in the left sidebar and set up at least one integration first.