# Bearconnect Documentation (Full) > Complete documentation for the Bearconnect LinkedIn automation platform. > Source: https://bearconnect.io/docs/ --- # Integrations Overview Bearconnect integrations let you automatically sync your LinkedIn outreach activity to your CRM, webhook endpoints, and other tools. When a lead accepts a connection request or you send a message, that event can be forwarded in real time to the systems your team already uses. This guide covers how integrations work, what you can connect, and how to set everything up. --- ## Table of Contents 1. [Getting to Integrations](#getting-to-integrations) 2. [Available Integrations](#available-integrations) 3. [Key Concepts](#key-concepts) 4. [Connecting an Integration](#connecting-an-integration) 5. [Connecting Integrations to a Campaign](#connecting-integrations-to-a-campaign) 6. [Event Types](#event-types) 7. [Exporting Leads](#exporting-leads) 8. [Glossary](#glossary) --- ## Getting to Integrations 1. Log in to your Bearconnect dashboard. 2. Click **Integrations** in the left sidebar. You will land on the **Integrations** page, which shows two sections: - **Connected Integrations** - Integrations you have already set up. - **Available Integrations** - Integrations you can add. --- ## Available Integrations ### Currently Live | Integration | Type | Description | | ------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | | **[HubSpot](https://www.hubspot.com/)** | CRM | Sync leads to HubSpot CRM, log activities, and create deals automatically. Connected via Legacy App Token. | | **[Pipedrive](https://www.pipedrive.com/)** | CRM | Sync leads to Pipedrive as Persons or Leads, log activities, and create deals on replies. Connected via API Token. | | **Custom Webhooks** | Webhook | Send events to any HTTPS endpoint with custom HTTP webhooks. Supports HMAC signature verification. | | **[Zapier](https://zapier.com/)** | Automation | Send events to Zapier Catch Hook triggers to power any Zap. No API key needed - paste your hook URL. | | **[Make](https://www.make.com/)** | Automation | Send events to Make (formerly Integromat) Custom Webhook modules to trigger scenarios. Paste your hook URL. | | **[n8n](https://n8n.io/)** | Automation | Send events to n8n webhook triggers with optional authentication (header token or basic auth). | All integrations allow **multiple instances** - you can connect more than one HubSpot account, multiple Zapier hooks, etc. ### Coming Soon - Salesforce - Zoho CRM - Slack ### Which Integration Should I Choose? | If you want to... | Use | | -------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Sync leads as contacts in your CRM and log LinkedIn activities on their timeline | **HubSpot** or **Pipedrive** | | Automatically create Deals when leads reply to your messages | **Pipedrive** (built-in) or **HubSpot** (via activity logging) | | Send events to thousands of apps without code | **Zapier** (easiest setup, largest app catalog) | | Build visual multi-step automation scenarios with branching | **Make** (visual scenario builder with routers and filters) | | Keep lead data on your own servers or build complex conditional workflows | **n8n** (self-hosted option, advanced logic nodes) | | Send raw event data to your own backend or internal tools | **Custom Webhooks** (full control, HMAC signature verification) | --- ## Key Concepts ### Integration vs. Mapping An **integration** is a connection to an external tool (e.g., your HubSpot account or a webhook URL). A **mapping** is the link between a specific campaign and an integration. You must map an integration to a campaign to start receiving events. ### Allowed Events vs. Enabled Events - **Allowed events** are the event types configured on the integration itself. They define what the integration _can_ handle. - **Enabled events** are the subset of allowed events that are actually turned on for a specific campaign mapping. They define what the integration _will_ receive from that campaign. For example, your HubSpot integration might allow all 4 event types, but a particular campaign mapping might only have "Connection Accepted" and "Message Sent" enabled. ### Integration Status Each connected integration shows a status: | Status | Meaning | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Active** | Connected and working normally. | | **Inactive** | The integration has been manually paused using the toggle switch. Events are not forwarded. Toggle it back on to resume. | | **Error** | The last sync or delivery encountered a problem. Check connection details. | | **Disconnected** | The integration has been disconnected or credentials have expired. | --- ## Connecting an Integration ### HubSpot 1. Go to **Integrations** in the left sidebar. 2. Find **HubSpot** in the Available Integrations section and click **Connect**. 3. Enter your Legacy App Token from HubSpot and a name for the integration. 4. Click **Connect**. For detailed setup instructions, see the [HubSpot Integration Guide](https://bearconnect.io/docs/integrations/hubspot/). ### Pipedrive 1. Go to **Integrations** in the left sidebar. 2. Find **Pipedrive** in the Available Integrations section and click **Connect**. 3. Enter your **Personal API Token** from Pipedrive and a name for the integration. 4. Click **Connect**. For detailed setup instructions, see the [Pipedrive Integration Guide](https://bearconnect.io/docs/integrations/pipedrive/). ### Custom Webhooks 1. Go to **Integrations** in the left sidebar. 2. Find **Custom Webhooks** in the Available Integrations section and click **Connect**. 3. Fill in the webhook details: - **Name** - A label for this webhook (e.g., "CRM Sync Webhook"). - **Endpoint URL** - The HTTPS URL that will receive events. - **HMAC Signature** - Optionally enable payload signing for security. - **Events** - Select which event types this webhook should handle. 4. Click **Create Webhook**. For detailed setup instructions, see the [Custom Webhook Guide](https://bearconnect.io/docs/integrations/webhook/). ### Zapier 1. Go to **Integrations** in the left sidebar. 2. Find **Zapier** in the Available Integrations section and click **Connect**. 3. Paste your Zapier Catch Hook URL and give the integration a name. 4. Select the events you want to forward and click **Connect**. For detailed setup instructions, see the [Zapier Integration Guide](https://bearconnect.io/docs/integrations/zapier/). ### Make (Integromat) 1. Go to **Integrations** in the left sidebar. 2. Find **Make** in the Available Integrations section and click **Connect**. 3. Paste your Make Custom Webhook URL and give the integration a name. 4. Select the events you want to forward and click **Connect**. For detailed setup instructions, see the [Make Integration Guide](https://bearconnect.io/docs/integrations/make/). ### n8n 1. Go to **Integrations** in the left sidebar. 2. Find **n8n** in the Available Integrations section and click **Connect**. 3. Paste your n8n **Production** Webhook URL, configure authentication if needed, and give the integration a name. 4. Select the events you want to forward and click **Connect**. For detailed setup instructions, see the [n8n Integration Guide](https://bearconnect.io/docs/integrations/n8n/). --- ## Connecting Integrations to a Campaign Once you have a connected integration, you need to map it to a campaign so events from that campaign are forwarded to the integration. ### How to Connect 1. Open a campaign from your dashboard. 2. Go to the **Integrations** tab within the campaign. 3. Click **Connect Integration**. 4. Select an integration from the dropdown (only integrations not yet mapped to this campaign are shown). 5. Choose which events to enable for this campaign. 6. Click **Connect**. ### Managing Campaign Mappings From the campaign's Integrations tab, you can: - **Toggle on/off** - Temporarily pause or resume event forwarding without removing the mapping. - **Edit events** - Click the settings icon to change which events are enabled. - **Disconnect** - Click the trash icon and confirm to remove the mapping entirely. Each mapping card shows: - The integration name and provider icon. - How many event types are enabled. - Event badges showing the first 6 enabled events. --- ## Event Types Events are the activities that get forwarded from Bearconnect to your integrations. The following events are currently available: ### Connection Events | Event | Description | | --------------------------- | ---------------------------------------------------- | | **Connection Request Sent** | A connection request was sent to a lead on LinkedIn. | | **Connection Accepted** | A lead accepted your LinkedIn connection request. | ### Message Events | Event | Description | | ------------------- | ----------------------------------------- | | **Message Sent** | A message was sent to a lead on LinkedIn. | | **Message Replied** | A lead replied to your LinkedIn message. | > **Note:** These are the 4 events currently available for use. Additional event categories - > including Campaign Events, Lead Events, Workflow Events, Engagement Events, and System Events - > are planned for future releases and will appear automatically in the event selection when ready. --- ## Exporting Leads You can manually export individual leads to any connected integration directly from the leads list. ### How to Export a Lead 1. Go to the **Leads** page. 2. Find the lead you want to export and click the **three-dot action menu** (⋮) on that row. 3. Click **Export**. 4. Select the integration you want to export to. 5. **For HubSpot**: You will see a second step to configure field mappings (Lifecycle Stage and Lead Status). You can customize these or click "Skip & Use Defaults." 6. **For Pipedrive**: You can choose the record type (Person or Lead), assign an owner, and apply labels. 7. **For Webhooks, Zapier, Make, and n8n**: The export happens immediately - no field mapping step is needed. ### What Gets Exported When you export a lead, the following data is sent to the integration: - First name, last name - Email, phone - LinkedIn profile URL and headline - Company name, position, location - Profile image URL - Connection and follower counts - Additional profile data (education, website, etc.) - LinkedIn account name and email (the account used for outreach) > **Note:** Not all lead fields are guaranteed to have a value. Only the lead's `id` and `firstName` > are always present. Fields like `email`, `phone`, `companyName`, `location`, and others may be > `null` if they are not available on the lead's LinkedIn profile. See the individual integration > guides for a complete field availability reference. For HubSpot, the lead is created or updated as a contact in your HubSpot CRM. For Pipedrive, the lead is created or updated as a Person (or Lead record, depending on your config). For webhooks, Zapier, Make, and n8n, the full lead data is sent as a JSON payload to your configured endpoint. --- ## Glossary | Term | Definition | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | | **Integration** | A connection to an external tool like HubSpot or a webhook URL. Configured in the Integrations section of the sidebar. | | **Mapping** | A link between a campaign and an integration that controls which events are forwarded. | | **Allowed Events** | The event types an integration is configured to handle (set at the integration level). | | **Enabled Events** | The subset of allowed events turned on for a specific campaign mapping. | | **Webhook** | An HTTP endpoint that receives event data as JSON payloads via POST requests. | | **Signing Secret** | An HMAC-SHA256 secret used to verify that webhook payloads genuinely come from Bearconnect. | | **Legacy App Token** | A HubSpot private app access token (format: `pat-xx-...`) used to connect HubSpot. | | **Lifecycle Stage** | A HubSpot field that tracks where a contact is in your sales pipeline (e.g., Subscriber, Lead, Opportunity). | | **Lead Status** | A HubSpot field that indicates the current state of a lead (e.g., New, Open, In Progress). | | **Catch Hook URL** | A Zapier-generated webhook URL that receives incoming data and triggers a Zap. | | **Custom Webhook URL** | A Make-generated webhook URL that receives data and triggers a scenario. | | **Production URL** | An n8n webhook URL (contains `/webhook/`) that stays active when the workflow is enabled. Distinct from test URLs. | | **Event Forwarding** | The automatic process of sending events from a campaign to mapped integrations in real time. | --- ## Next Steps - [HubSpot Integration Guide](https://bearconnect.io/docs/integrations/hubspot/) - Detailed setup and usage for HubSpot. - [Pipedrive Integration Guide](https://bearconnect.io/docs/integrations/pipedrive/) - Detailed setup and usage for Pipedrive. - [Custom Webhook Guide](https://bearconnect.io/docs/integrations/webhook/) - Detailed setup and usage for webhooks. - [Zapier Integration Guide](https://bearconnect.io/docs/integrations/zapier/) - Detailed setup and usage for Zapier. - [Make Integration Guide](https://bearconnect.io/docs/integrations/make/) - Detailed setup and usage for Make. - [n8n Integration Guide](https://bearconnect.io/docs/integrations/n8n/) - Detailed setup and usage for n8n. --- # HubSpot Integration Guide Connect your HubSpot CRM to Bearconnect to automatically sync leads, log LinkedIn activities, and keep your sales pipeline up to date. This guide walks you through every step - from connecting your HubSpot account to exporting leads and configuring sync settings. --- ## Table of Contents 1. [What You Need](#what-you-need) 2. [Connecting HubSpot](#connecting-hubspot) 3. [After Connecting](#after-connecting) 4. [Connecting HubSpot to a Campaign](#connecting-hubspot-to-a-campaign) 5. [Exporting Leads to HubSpot](#exporting-leads-to-hubspot) 6. [HubSpot Settings](#hubspot-settings) 7. [Token Management](#token-management) 8. [Testing Your Connection](#testing-your-connection) 9. [Disconnecting HubSpot](#disconnecting-hubspot) 10. [Troubleshooting](#troubleshooting) --- ## Quick Start Already have a HubSpot Legacy App Token? Here is the fastest path: 1. In Bearconnect: Go to **Integrations > HubSpot > Connect**. 2. Enter a name and paste your Legacy App Token (starts with `pat-`). 3. Click **Test Token** to verify, then click **Connect**. 4. Open a campaign > **Integrations** tab > **Connect Integration** > select HubSpot and enable events. If you do not have a Legacy App Token yet, follow the full setup below. --- ## What You Need Before you start, make sure you have: - A **Bearconnect account** with an active subscription. - A **HubSpot account** (Free, Starter, Professional, or Enterprise). - **Admin or Super Admin permissions** in your HubSpot account (required for creating legacy apps). --- ## Connecting HubSpot Go to **Integrations** in the left sidebar of your Bearconnect dashboard. Find **HubSpot** in the Available Integrations section and click **Connect**. You will need a [Legacy App Token](https://developers.hubspot.com/docs/api/private-apps) from HubSpot. If you do not have one yet, follow the steps below to create it. ### Step 1: Create a Legacy App in HubSpot 1. Log in to your [HubSpot account](https://app.hubspot.com). 2. Go to **Development** in the top navigation. 3. Click **Legacy apps** in the left sidebar. 4. Click **Create legacy app** and select **Private**. ### Step 2: Configure Scopes Under the [**Scopes**](https://developers.hubspot.com/docs/api/working-with-oauth#scopes) tab of your new app, you need to grant the following permissions. You can copy the complete list from the Bearconnect connection form (there is a "Copy All" button). **Required Scopes:** ```text crm.objects.contacts.read crm.objects.contacts.write crm.objects.companies.read crm.objects.companies.write crm.objects.deals.read crm.objects.deals.write crm.schemas.contacts.read crm.schemas.contacts.write crm.schemas.companies.read crm.schemas.companies.write crm.schemas.deals.read crm.schemas.deals.write crm.lists.read crm.lists.write timeline ``` Search for each scope in HubSpot's scope selector and enable it. The "Copy All" button in Bearconnect copies all scope names as a comma-separated list that you can use to search one by one. **Optional Scopes (Enterprise only):** If you are on a HubSpot Enterprise plan and need access to sensitive or highly sensitive data fields, check the "Include sensitive & highly sensitive data scopes" checkbox in the Bearconnect connection form to see the additional scopes: ```text crm.objects.contacts.sensitive.read crm.objects.companies.sensitive.read crm.objects.deals.sensitive.read crm.objects.contacts.highly_sensitive.read crm.objects.companies.highly_sensitive.read crm.objects.deals.highly_sensitive.read ``` These are read-only scopes. Most users do not need them. ### Step 3: Create the App and Copy the Token 1. Click **Create app** in HubSpot. 2. Go to the **Auth** tab. 3. Copy the **Access Token** (it starts with `pat-`). ### Step 4: Connect in Bearconnect 1. Back in Bearconnect, enter a **Name** for this integration (e.g., "My HubSpot"). 2. Paste the token into the **Legacy App Access Token** field. 3. (Optional) Click **Test Token** to verify the connection before saving. 4. Click **Connect**. > **Note:** The token format is `pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. The form validates > this format and will show an error if the token is malformed. --- ## After Connecting Once connected, your HubSpot integration appears in the **Connected Integrations** section. Clicking on it opens a detail panel showing: - **Connection Status** - Active, Error, or Disconnected. - **Connection Type** - Legacy App (shown as a badge). - **Sync Statistics** - Number of contacts synced, sync errors, and last sync time. - **Sync Settings** - Current sync mode, direction, and auto-sync status (read-only in the detail panel; editable in HubSpot Settings). - **Features** - Contact Sync, Activity Logging, Deal Creation, Two-way Sync. - **Connection Details** - When it was connected, provider type, integration ID, and last update time. ### What Happens Automatically When you connect HubSpot, Bearconnect: - Creates custom properties in your HubSpot account for tracking LinkedIn activity. - Configures the integration with all currently available events pre-selected as allowed events. --- ## Connecting HubSpot to a Campaign To start receiving events from a campaign, you need to map HubSpot to that campaign. 1. Open the campaign from your dashboard. 2. Go to the **Integrations** tab. 3. Click **Connect Integration**. 4. Select your HubSpot integration from the dropdown. 5. Choose which events to enable: - **Connection Request Sent** - When a connection request is sent to a lead. - **Connection Accepted** - When a lead accepts your connection request. - **Message Sent** - When a message is sent to a lead. - **Message Replied** - When a lead replies to your message. 6. Click **Connect**. You can select individual events or use the category checkboxes to select/deselect all events in a category at once. ### Managing the Mapping After connecting, the mapping card shows on the campaign's Integrations tab: - **Toggle switch** - Turn event forwarding on or off without deleting the mapping. - **Settings icon** - Edit which events are enabled. - **Trash icon** - Disconnect the integration from this campaign. --- ## Exporting Leads to HubSpot You can manually export individual leads as contacts to HubSpot. ### Step 1: Start the Export 1. Go to the **Leads** page. 2. Find the lead you want to export and click the **three-dot action menu** (⋮) on that row. 3. Click **Export**. 4. Select your HubSpot integration from the dropdown. 5. Click **Export**. ### Step 2: Configure Field Mappings Since you selected HubSpot, a second step appears asking you to configure field mappings: - **Lifecycle Stage** - Choose the HubSpot lifecycle stage for the exported contact (e.g., Subscriber, Lead, Marketing Qualified Lead, Sales Qualified Lead, Opportunity, Customer, Evangelist). - **Lead Status** - Choose the lead status (e.g., New, Open, In Progress, Open Deal, Unqualified, Attempted to Contact, Connected, Bad Timing). You have three options: - **Export** - Save your selections and export the lead. - **Skip & Use Defaults** - Export using default values (first option in each dropdown). - **Back** - Return to the integration selection step. > **Tip:** Your field mapping preferences are saved per integration. The next time you export to the > same HubSpot integration, your previous selections are pre-filled. ### What Gets Sent to HubSpot The following lead data is synced to HubSpot as a contact: | Bearconnect Field | HubSpot Field | Notes | | -------------------- | ----------------- | ----------------------------------- | | First Name | `firstname` | | | Last Name | `lastname` | | | Email | `email` | Primary deduplication key | | Phone | `phone` | | | Company Name | `company` | | | Position / Job Title | `jobtitle` | | | LinkedIn Profile URL | `hs_linkedin_url` | HubSpot built-in LinkedIn URL field | | Website | `website` | Lead's personal or company website | | Location | `city` | Mapped to the City field | | Lifecycle Stage | `lifecyclestage` | Configured in the export dialog | | Lead Status | `hs_lead_status` | Configured in the export dialog | If the contact already exists in HubSpot (matched by email or LinkedIn URL), it is updated rather than duplicated. ### Custom BearConnect Properties In addition to the standard fields above, Bearconnect automatically creates and populates the following custom properties on every synced HubSpot contact: | Custom Property | Value | Description | | ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------ | | `bc_lead_id` | Bearconnect lead ID | Links the HubSpot contact back to the lead in Bearconnect. | | `bc_lead_url` | Direct link to the lead in Bearconnect | Click this URL to jump directly to the lead's profile in your Bearconnect dashboard. | | `bc_campaign_name` | Campaign name | The name of the campaign the lead was synced from. | | `bc_synced_at` | ISO timestamp | When the contact was last synced from Bearconnect. | These properties are created automatically during the first sync. If they are manually deleted from HubSpot, Bearconnect will recreate them on the next sync. --- ## HubSpot Settings To access HubSpot-specific settings: 1. Go to **Integrations** in the left sidebar. 2. Click on your connected HubSpot integration. 3. In the detail panel, click **Settings** (or navigate directly to **Integrations > HubSpot > Settings**). ### Available Settings | Setting | Options | Description | | ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Automatic Sync** | On / Off | When enabled, events are automatically forwarded to HubSpot as they occur. | | **Sync Mode** | Real-time, Batch (15 min), Manual Only | Controls how often events are sent. Real-time sends immediately; Batch groups events into 15-minute intervals; Manual means you must trigger syncs yourself. | | **Sync Direction** | Outbound Only, Inbound Only, Bidirectional | Controls the direction of data flow. Outbound sends data from Bearconnect to HubSpot. Inbound pulls data from HubSpot. Bidirectional does both. | ### Connection Status Panel The settings page also shows: - **Contacts Synced** - Total number of contacts successfully synced. - **Sync Errors** - Number of errors encountered. - **Last Sync** - When the last successful sync occurred. - **Test Connection** button - Verifies that the connection to HubSpot is still working. --- ## Token Management ### Token Rotation Warning Bearconnect tracks how old your token is. HubSpot recommends rotating tokens every **180 days** (6 months) for security. When your token is older than 180 days, you will see a warning banner: - Shows how many days since the token was created. - Shows how many days past the recommended rotation period. - Provides a link to HubSpot's token rotation documentation. - Can be dismissed (the warning will not reappear until the next check). ### How to Rotate Your Token 1. Go to your HubSpot account > **Development** > **Legacy apps**. 2. Open your private app. 3. Go to the **Auth** tab. 4. Click **Rotate token** to generate a new token. 5. Copy the new token. 6. In Bearconnect, reconnect using the new token. > **Important:** After rotating, the old token stops working. Make sure to update the token in > Bearconnect promptly. --- ## Testing Your Connection You can verify that your HubSpot connection is working at any time: 1. Go to **Integrations** in the left sidebar. 2. Click on your HubSpot integration to open the detail panel. 3. Click **Test Connection**. 4. If successful, you will see a "Connection test successful" message. 5. If it fails, check the error message for details (common issues: expired token, revoked access, network problems). --- ## Disconnecting HubSpot To disconnect your HubSpot integration: 1. Go to **Integrations** in the left sidebar. 2. Click on your connected HubSpot integration. 3. Click **Delete** or **Disconnect**. 4. Confirm the action. ### What Happens When You Disconnect - All campaign mappings using this integration are removed. - Event forwarding stops immediately. - Previously synced contacts in HubSpot are **not** deleted or modified. - Custom properties created by Bearconnect remain in your HubSpot account. - You can reconnect at any time by going through the setup process again. --- ## Troubleshooting ### "Connection test failed" Your token may have expired or been rotated. Go to HubSpot > Development > Legacy apps, open your app, and check the Auth tab. If the token has been rotated, copy the new token and reconnect in Bearconnect. ### "Invalid token format" The Legacy App Token must start with `pat-` and follow the format `pat-xx-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. Make sure you copied the full token from HubSpot without any extra spaces. ### Events are not appearing in HubSpot 1. Check that the integration is in **Active** status (Integrations > click on HubSpot). 2. Verify the campaign mapping is active (Campaign > Integrations tab > toggle should be on). 3. Check that the relevant event types are enabled in the campaign mapping. 4. Verify that **Automatic Sync** is turned on in HubSpot Settings. 5. If using Batch sync mode, events may take up to 15 minutes to appear. ### "Sync error" showing on the integration Click on the integration to see the error details. Common causes: - HubSpot API rate limits - Usually resolves automatically. Wait a few minutes and try again. - Missing required properties - Bearconnect creates custom properties automatically, but if they were manually deleted in HubSpot, you may need to reconnect. - Insufficient permissions - Ensure all required scopes are granted on your HubSpot app. ### Lead export shows "skipped" This means the lead already exists in HubSpot and no new data was needed. This is not an error - it means HubSpot already has this contact with the same or newer data. --- # Pipedrive Integration Guide Connect your Pipedrive CRM to Bearconnect to automatically sync leads as Persons (or Leads), log LinkedIn activities, and create Deals when leads reply to your messages. This guide walks you through every step - from connecting your Pipedrive account to exporting leads and configuring sync settings. --- ## Table of Contents 1. [What You Need](#what-you-need) 2. [Connecting Pipedrive](#connecting-pipedrive) 3. [After Connecting](#after-connecting) 4. [Connecting Pipedrive to a Campaign](#connecting-pipedrive-to-a-campaign) 5. [Exporting Leads to Pipedrive](#exporting-leads-to-pipedrive) 6. [Pipedrive Settings](#pipedrive-settings) 7. [Person vs Lead Record Type](#person-vs-lead-record-type) 8. [Deal Creation](#deal-creation) 9. [Activity Logging](#activity-logging) 10. [Testing Your Connection](#testing-your-connection) 11. [Disconnecting Pipedrive](#disconnecting-pipedrive) 12. [Troubleshooting](#troubleshooting) --- ## Quick Start Already have your Pipedrive API Token? Here is the fastest path: 1. In Bearconnect: Go to **Integrations > Pipedrive > Connect**. 2. Enter a name and paste your Personal API Token. 3. Click **Connect**. 4. Open a campaign > **Integrations** tab > **Connect Integration** > select Pipedrive, choose events, record type, and owner > click **Connect**. For full setup details, continue below. --- ## What You Need Before you start, make sure you have: - A **Bearconnect account** with an active subscription. - A **Pipedrive account** (Essential, Advanced, Professional, Power, or Enterprise). - **Admin permissions** in your Pipedrive account (required for API token access). --- ## Connecting Pipedrive Go to **Integrations** in the left sidebar of your Bearconnect dashboard. Find **Pipedrive** in the Available Integrations section and click **Connect**. You will need a [Personal API Token](https://pipedrive.readme.io/docs/how-to-find-the-api-token) from Pipedrive. If you do not have one yet, follow the steps below. ### Step 1: Find Your API Token in Pipedrive 1. Log in to your [Pipedrive account](https://app.pipedrive.com). 2. Click your **profile icon** in the top-right corner. 3. Go to **Settings** > **Personal preferences**. 4. Click the **API** tab. 5. Copy your **Personal API Token**. ### Step 2: Connect in Bearconnect 1. Back in Bearconnect, enter a **Name** for this integration (e.g., "My Pipedrive"). 2. Paste the token into the **API Token** field. 3. Click **Connect**. --- ## After Connecting Once connected, your Pipedrive integration appears in the **Connected Integrations** section. Clicking on it opens a detail panel showing: - **Connection Status** - Active, Error, or Disconnected. - **Connection Type** - API Token (shown as a badge). - **Sync Statistics** - Number of persons synced, sync errors, and last sync time. - **Sync Settings** - Current sync mode, direction, and auto-sync status (read-only in the detail panel; editable in Pipedrive Settings). - **Features** - Person Sync, Activity Logging, Deal Creation. - **Connection Details** - When it was connected, provider type, integration ID, and last update time. ### What Happens Automatically When you connect Pipedrive, Bearconnect: - Validates the connection by querying your Pipedrive account. - Configures the integration with all currently available events pre-selected as allowed events. ### Multiple Instances You can connect multiple Pipedrive accounts to Bearconnect. Each connection is managed independently with its own credentials, campaign mappings, and sync settings. --- ## Connecting Pipedrive to a Campaign To start receiving events from a campaign, you need to map Pipedrive to that campaign. 1. Open the campaign from your dashboard. 2. Go to the **Integrations** tab. 3. Click **Connect Integration**. 4. Select your Pipedrive integration from the dropdown. 5. Choose which events to enable: - **Connection Request Sent** - When a connection request is sent to a lead. - **Connection Accepted** - When a lead accepts your connection request. - **Message Sent** - When a message is sent to a lead. - **Message Replied** - When a lead replies to your message. > **Coming Soon:** Additional events (Lead Added to Campaign, InMail Replied, Profile Viewed, Lead > Status Changed) are planned for future releases. 6. Optionally configure: - **Record Type** - Person (default) or Lead. See [Person vs Lead Record Type](#person-vs-lead-record-type). - **Owner** - Assign a Pipedrive user as the owner of created records. - **Labels** - Apply labels to created records. 7. Click **Connect**. You can select individual events or use the category checkboxes to select/deselect all events in a category at once. ### What Happens on Each Event | Event | Pipedrive Action | | ----------------------- | ----------------------------------------------------------------------------------------------- | | Connection Request Sent | Log Activity (a Person is created if one does not already exist, so the activity can be linked) | | Connection Accepted | Upsert Person (or Lead, based on your record type setting) + Log Activity | | Message Sent | Log Activity (a Person is created if one does not already exist, so the activity can be linked) | | Message Replied | Upsert Person + Create Deal + Log Activity | > **Note on activity-only events:** For Connection Request Sent and Message Sent, Bearconnect needs > a Person record in Pipedrive to attach the activity to. If a matching Person does not exist yet, > one is automatically created using the lead's name and email. This ensures you have a complete > activity timeline in Pipedrive from the very first touchpoint. > **Future Events:** Additional events such as Lead Added to Campaign, InMail Sent, InMail Replied, > Profile Viewed, and Lead Status Changed are planned and will be added in upcoming releases. ### Managing the Mapping After connecting, the mapping card shows on the campaign's Integrations tab: - **Toggle switch** - Turn event forwarding on or off without deleting the mapping. - **Settings icon** - Edit which events are enabled, change record type, owner, or labels. - **Trash icon** - Disconnect the integration from this campaign. --- ## Exporting Leads to Pipedrive You can manually export individual leads as Persons (or Leads) to Pipedrive. ### Step 1: Start the Export 1. Go to the **Leads** page. 2. Find the lead you want to export and click the **three-dot action menu** (⋮) on that row. 3. Click **Export**. 4. Select your Pipedrive integration from the dropdown. ### Step 2: Configure Export Settings Since you selected Pipedrive, a second step appears asking you to configure export settings: - **Record Type** - Choose whether to create a Person or a Lead in Pipedrive. - **Owner** - Assign a Pipedrive user as the owner of the record. - **Labels** - Apply labels to the exported record. You have three options: - **Export** - Save your selections and export the lead. - **Skip & Use Defaults** - Export using default values (Person record type, no specific owner or labels). - **Back** - Return to the integration selection step. ### What Gets Sent to Pipedrive The following lead data is synced to Pipedrive Person fields: | Bearconnect Field | Pipedrive Person Field | Format | | ---------------------- | ---------------------- | -------------------------------------------------------------------------------------- | | First Name + Last Name | `name` | Combined into a single name field (defaults to "Unknown" if both are empty) | | Email | `emails` | Primary email, labeled as "work" - format: `[{ value, primary: true, label: 'work' }]` | | Phone | `phones` | Primary phone, labeled as "work" - format: `[{ value, primary: true, label: 'work' }]` | | Position / Job Title | `job_title` | Mapped directly | These are the **only** fields synced to the Pipedrive Person record. ### Deduplication Logic Bearconnect checks for existing Persons in Pipedrive before creating a new one to prevent duplicates: 1. **Email match (primary)** - Searches Pipedrive for an exact email match. If found, the existing Person is updated. 2. **Name match (fallback)** - If no email is available on the lead, Bearconnect falls back to searching by full name. If found, the existing Person is updated. 3. **Create new** - If neither match is found, a new Person is created. > **Tip:** For the most reliable deduplication, ensure your leads in Bearconnect have email > addresses populated. Name-only matching is less reliable because multiple people can share the > same name. > **Important notes on field mapping:** > > - **Company / Organization** - `companyName` is included in the event payload but does **not** > auto-create or link an Organization in Pipedrive. Pipedrive's v2 API only accepts `org_id` (an > existing Organization ID), not an organization name, so Bearconnect cannot create > Organizations automatically. > - **Other lead data** - Fields such as `profileUrl`, `profileHeadline`, `companyName`, > `location`, `website`, and `education` are included in the event payload sent to Pipedrive but > are **not** mapped to Pipedrive Person fields. They are available in activity notes. > - **Custom fields** - If you need additional lead data in Pipedrive, you can create custom > fields in Pipedrive and use Pipedrive's built-in automations or workflows to populate them > from activity notes or other sources. --- ## Pipedrive Settings To access Pipedrive-specific settings: 1. Go to **Integrations** in the left sidebar. 2. Click on your connected Pipedrive integration. 3. In the detail panel, click **Settings** (or navigate directly to **Integrations > Pipedrive > Settings**). ### Available Settings | Setting | Options | Description | | ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Automatic Sync** | On / Off | When enabled, events are automatically forwarded to Pipedrive as they occur. | | **Sync Mode** | Real-time, Batch (15 min), Manual Only | Controls how often events are sent. Real-time sends immediately; Batch groups events into 15-minute intervals; Manual means you must trigger syncs yourself. | | **Sync Direction** | Outbound Only, Inbound Only, Bidirectional | Controls the direction of data flow. Outbound sends data from Bearconnect to Pipedrive. Inbound pulls data from Pipedrive. Bidirectional does both. | ### Connection Status Panel The settings page also shows: - **Persons Synced** - Total number of persons successfully synced. - **Sync Errors** - Number of errors encountered. - **Last Sync** - When the last successful sync occurred. - **Test Connection** button - Verifies that the connection to Pipedrive is still working. --- ## Person vs Lead Record Type Pipedrive has two distinct record types that Bearconnect can create: - **Person** (default) - A standard Pipedrive contact. Best for most use cases. Persons appear in your Pipedrive contacts list and can be associated with Deals, Activities, and Organizations. - **Lead** - A Pipedrive Lead object representing an unqualified opportunity. Useful if you want to keep your Persons list clean and qualify leads before promoting them to full contacts. The record type is configured per campaign mapping in the metadata settings. You can also choose the record type when manually exporting leads. ### How Lead Record Type Works When you choose the Lead record type, Bearconnect: 1. Creates or finds the Person first (a Person is always needed as the anchor record). 2. Creates a Lead linked to that Person, or updates the existing Lead if one already exists for that Person. 3. Applies your configured **Owner** and **Labels** to the Lead record. > **Important:** Reply events (Message Replied) always create Person records and Deals regardless of > the record type setting. The Lead record type only affects how connection acceptance and initial > sync events are handled. --- ## Deal Creation Bearconnect automatically creates Deals in Pipedrive when certain events occur: - **Message Replied** - A lead replies to your LinkedIn message. > **Coming Soon:** Deal creation on InMail Replied events will be available in a future release. ### Deal Details | Field | Value | Example | | ----------------- | ------------------------------------------- | ------------------------------------ | | **Title** | `{First Name} {Last Name} - LinkedIn Reply` | "Jane Doe - LinkedIn Reply" | | **Status** | Open | Always created with Open status | | **Linked Person** | The Person record associated with the lead | Linked automatically via `person_id` | Deals are created to help you track warm leads in your Pipedrive sales pipeline. You can customize the deal stage and pipeline from within Pipedrive after creation. > **Note:** If deal creation fails for any reason (e.g., API rate limit), the activity is still > logged successfully. Deal creation is non-blocking - it does not prevent the rest of the event > from being processed. --- ## Activity Logging Bearconnect logs LinkedIn activities as completed tasks in Pipedrive. Activities are linked to the corresponding Person record. ### Activity Details - **Subject** - Includes the campaign name (e.g., "LinkedIn connection request sent via Q1 Outreach"). - **Note** - Contains the campaign name, timestamp, and event type. - **Status** - Marked as completed (done). Activities are logged for all enabled events in your campaign mapping, giving you a full timeline of LinkedIn interactions directly in Pipedrive. --- ## Testing Your Connection You can verify that your Pipedrive connection is working at any time: 1. Go to **Integrations** in the left sidebar. 2. Click on your Pipedrive integration to open the detail panel. 3. Click **Test Connection**. 4. If successful, you will see a "Connection test successful" message. 5. If it fails, check the error message for details (common issues: expired token, revoked access, network problems). --- ## Disconnecting Pipedrive To disconnect your Pipedrive integration: 1. Go to **Integrations** in the left sidebar. 2. Click on your connected Pipedrive integration. 3. Click **Delete** or **Disconnect**. 4. Confirm the action. ### What Happens When You Disconnect - All campaign mappings using this integration are removed. - Event forwarding stops immediately. - Previously synced Persons, Leads, Deals, and Activities in Pipedrive are **not** deleted or modified. - You can reconnect at any time by going through the setup process again. --- ## Troubleshooting ### "Connection failed" Your API token may be incorrect or your Pipedrive account may be inactive. Verify the token by going to Pipedrive > Settings > Personal preferences > API and copying the token again. Ensure your Pipedrive account is active and in good standing. ### Duplicate persons appearing in Pipedrive Bearconnect searches by email first (exact match), then by full name (exact match) as a fallback. For best deduplication results, ensure your leads in Bearconnect have email addresses populated. Leads without email addresses are matched by name only, which is less reliable because multiple people can share the same name. ### Activities not appearing in Pipedrive 1. Check that the integration is in **Active** status (Integrations > click on Pipedrive). 2. Verify the campaign mapping is active (Campaign > Integrations tab > toggle should be on). 3. Check that the relevant event types are enabled in the campaign mapping. 4. Verify that **Automatic Sync** is turned on in Pipedrive Settings. 5. If using Batch sync mode, activities may take up to 15 minutes to appear. ### "Token expired" error Verify the token is still valid in Pipedrive > Settings > Personal preferences > API. If the token has been regenerated, copy the new token, disconnect the integration in Bearconnect, and reconnect with the updated token. ### Wrong owner assigned to records Check the owner setting in your campaign mapping metadata or export settings. The owner must be a valid, active user in your Pipedrive account. If no owner is specified, records are assigned to the API token owner by default. ### "Sync error" showing on the integration Click on the integration to see the error details. Common causes: - Pipedrive API rate limits - Usually resolves automatically. Wait a few minutes and try again. - Invalid or deactivated Pipedrive account - Verify your account is active. - Insufficient permissions - Ensure the API token owner has admin access in Pipedrive. ### Lead export shows "skipped" This means the person already exists in Pipedrive and no new data was needed. This is not an error - it means Pipedrive already has this contact with the same or newer data. --- # Zapier Integration Guide Zapier integration lets you send Bearconnect LinkedIn outreach events to a Zapier Catch Hook URL, which triggers Zaps in your Zapier account. Whenever a lead accepts a connection, a message is sent, or another tracked event occurs, Bearconnect sends a JSON payload to your configured Catch Hook URL. This is ideal for pushing lead data into CRMs, spreadsheets, email tools, Slack, or any of the thousands of apps Zapier connects to. --- ## Table of Contents 1. [What You Need](#what-you-need) 2. [Getting Your Zapier Catch Hook URL](#getting-your-zapier-catch-hook-url) 3. [Connecting Zapier in Bearconnect](#connecting-zapier-in-bearconnect) 4. [After Connecting](#after-connecting) 5. [Connecting Zapier to a Campaign](#connecting-zapier-to-a-campaign) 6. [Exporting Leads via Zapier](#exporting-leads-via-zapier) 7. [Payload Format](#payload-format) 8. [Mapping Fields in Your Zap](#mapping-fields-in-your-zap) 9. [Testing Your Connection](#testing-your-connection) 10. [Managing Your Zapier Integration](#managing-your-zapier-integration) 11. [Use Cases](#use-cases) 12. [Troubleshooting](#troubleshooting) --- ## Quick Start Already familiar with Zapier? Here is the fastest path: 1. In Zapier: Create a Zap with **Webhooks by Zapier > Catch Hook** trigger. Copy the hook URL. 2. In Bearconnect: Go to **Integrations > Zapier > Connect**. Paste the URL, select events, click **Connect**. 3. In Bearconnect: Click **Test Connection** on the Zapier integration to send sample data. 4. In Zapier: Click **Test trigger** in your Catch Hook step to detect the data structure. Add your action steps. 5. In Bearconnect: Open a campaign > **Integrations** tab > **Connect Integration** > select your Zapier integration and enable events. --- ## What You Need - A **Bearconnect account** with an active subscription. - A **[Zapier account](https://zapier.com)** (Free or paid). - A **Zap** with a "[Webhooks by Zapier](https://zapier.com/apps/webhook/integrations)" trigger configured as a **Catch Hook**. --- ## Getting Your Zapier Catch Hook URL Before connecting in Bearconnect, you need a Catch Hook URL from Zapier. 1. Log in to your **Zapier** account and click **Create Zap** (or **Make a Zap**). 2. In the trigger step, search for and select **Webhooks by Zapier**. 3. Choose **Catch Hook** as the trigger event. > **Important:** Select **Catch Hook**, not **Catch Raw Hook**. Catch Hook automatically parses the > JSON payload. Catch Raw Hook gives you the raw request body, which is not what you need for this > integration. 4. Click **Continue** through the setup steps until Zapier displays your unique webhook URL. 5. Copy the URL. It will look like this: ```text https://hooks.zapier.com/hooks/catch/123456/abcdef/ ``` > **Important:** Do not complete the "Test trigger" step in Zapier yet. You will trigger a test from > Bearconnect after connecting, which will send sample data for Zapier to detect. Keep this URL ready for the next step. --- ## Connecting Zapier in Bearconnect 1. Go to **Integrations** in the left sidebar of your Bearconnect dashboard. 2. Find **Zapier** in the Available Integrations section and click **Connect**. 3. A dialog opens with the following fields: ### Required Fields | Field | Description | | ------------------ | ------------------------------------------------------------------------------------------------------ | | **Name** | A label to identify this connection (e.g., "Zapier - CRM Sync", "Zapier - Slack Alerts"). | | **Catch Hook URL** | The Zapier Catch Hook URL you copied in the previous step (must be an `https://hooks.zapier.com` URL). | ### 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 Zapier (e.g., `X-Source: bearconnect`). | | **Timeout (ms)** | 30000 | 5000–60000 | How long to wait for Zapier to respond before marking the delivery as failed. | 4. Click **Connect**. --- ## After Connecting Your Zapier integration now appears in the **Connected Integrations** section. Click on it to open the detail panel, which shows: ### Hook URL Your configured Catch Hook 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 (Zapier). - Integration ID. - Last updated timestamp. --- ## Connecting Zapier to a Campaign To receive events from a specific campaign, you must map the Zapier integration to that campaign. 1. Open a campaign from your dashboard. 2. Go to the **Integrations** tab. 3. Click **Connect Integration**. 4. Select your Zapier integration from the dropdown. 5. Choose which events to enable for this campaign (only events that are in the integration's allowed events list appear here). 6. 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 Zapier integration itself is not deleted). --- ## Exporting Leads via Zapier You can manually export a lead to your Zapier integration. 1. Go to the **Leads** page. 2. Find the lead you want to export and click the **three-dot action menu** on that row. 3. Click **Export**. 4. Select your Zapier integration from the dropdown. 5. Click **Export**. The lead data is sent immediately as a JSON payload to your Catch Hook URL, triggering your Zap. --- ## Payload Format Every delivery to Zapier is an HTTP POST request with a JSON body. The payload format is universal across all Bearconnect integration providers (Custom Webhooks, Zapier, Make, and n8n). All providers receive the exact same structure. ### Event Payload ```json { "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 your Zap, use Zapier's built-in "Formatter by Zapier" step with "Text > Default Value" > to handle missing fields. For example, set a default value for `data.lead.email` so your > downstream action does not fail when email is absent. ### 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 sent to Zapier includes: | Header | Value | | -------------- | ------------------------------------------------ | | `Content-Type` | `application/json` | | `User-Agent` | `Bearconnect/1.0` | | Custom headers | Any headers you configured in Advanced Settings. | --- ## Mapping Fields in Your Zap After Bearconnect sends a test payload (or a real event) to your Catch Hook URL, Zapier automatically detects the data structure. You can then map these fields in your Zap's action steps. ### Available Fields Once Zapier detects the payload, you will see fields organized like this in the Zap editor: | Zapier Field Path | Example Value | Description | | ---------------------------- | --------------------------------------- | ---------------------------------------------- | | `event` | `connection_request_accepted` | The event type that triggered the Zap. | | `timestamp` | `2026-02-13T10:30:00.000Z` | When the event occurred. | | `data.lead.firstName` | `Jane` | Lead's first name. | | `data.lead.lastName` | `Smith` | Lead's last name. | | `data.lead.email` | `jane.smith@example.com` | Lead's email address. | | `data.lead.phone` | `+1-555-0123` | Lead's phone number. | | `data.lead.profileUrl` | `https://www.linkedin.com/in/janesmith` | Lead's LinkedIn profile URL. | | `data.lead.profileHeadline` | `VP of Sales at Acme Corp` | Lead's LinkedIn headline. | | `data.lead.position` | `VP of Sales` | Lead's job title. | | `data.lead.companyName` | `Acme Corp` | Lead's company name. | | `data.lead.location` | `San Francisco, CA` | Lead's location. | | `data.campaign.name` | `Q1 Outreach` | Name of the campaign that triggered the event. | | `data.linkedInAccount.name` | `Sales Team Account` | Name of the LinkedIn account used. | | `data.linkedInAccount.email` | `john.smith@example.com` | Login email of the LinkedIn account used. | | `metadata.eventId` | `evt_abc123def456` | Unique event identifier. | ### How to Map Fields 1. In your Zap, add an action step (e.g., Google Sheets, HubSpot, Slack). 2. In the action's field configuration, click into any field. 3. Zapier shows the detected fields from Bearconnect's payload. 4. Select the appropriate field (e.g., map `data.lead.firstName` to a "First Name" column in Google Sheets). > **Tip:** If you do not see the Bearconnect fields in your action step, go back to the trigger step > and click "Test trigger" to re-detect the data structure. Make sure you have sent a test from > Bearconnect first. --- ## Testing Your Connection You can send a test request to verify your Catch Hook URL is reachable and Zapier is detecting the payload correctly. 1. Go to **Integrations** in the left sidebar. 2. Click on your Zapier integration to open the detail panel. 3. Click **Test Connection**. 4. If successful, you will see "Test successful" with the HTTP status code (e.g., 200). 5. If it fails, the error message will indicate the problem (timeout, invalid URL, non-2xx status code, etc.). The test sends a sample payload to your Catch Hook URL. The test payload is identical in structure to real event payloads - the same fields and format, with only sample values differing. Zapier auto-detects the data structure from this test payload, making all fields available in your Zap's action steps. > **Important:** After testing from Bearconnect, go back to the Zapier editor and click "Test > trigger" in your Catch Hook trigger step. Zapier will pick up the sample data Bearconnect just > sent. --- ## Managing Your Zapier Integration ### Editing the Integration To change the name, URL, events, or other settings: 1. Go to **Integrations** in the left sidebar. 2. Click on the Zapier integration you want to edit. 3. Make your changes in the detail panel. 4. Save. ### Deleting the Integration 1. Go to **Integrations** in the left sidebar. 2. Click on the Zapier integration you want to delete. 3. Click **Delete** and confirm. When you delete a Zapier integration: - All campaign mappings using it are removed. - Event forwarding stops immediately. - Delivery history is no longer tracked. --- ## Use Cases ### Push new LinkedIn connections to a Google Sheet 1. Create a Zap with a Catch Hook trigger. 2. Add a "Google Sheets - Create Spreadsheet Row" action. 3. Map `data.lead.firstName`, `data.lead.lastName`, `data.lead.email`, `data.lead.companyName`, and `data.lead.profileUrl` to columns in your sheet. 4. In Bearconnect, enable the **Connection Accepted** event on the campaign mapping. ### Create CRM contacts when connections are accepted 1. Create a Zap with a Catch Hook trigger. 2. Add a "HubSpot - Create Contact" (or Salesforce, [Pipedrive](https://bearconnect.io/docs/integrations/pipedrive/), etc.) action. 3. Map `data.lead.firstName`, `data.lead.lastName`, `data.lead.email`, `data.lead.companyName`, and `data.lead.position` to the CRM contact fields. 4. In Bearconnect, enable the **Connection Accepted** event on the campaign mapping. ### Send Slack notifications when leads reply 1. Create a Zap with a Catch Hook trigger. 2. Add a "Slack - Send Channel Message" action. 3. Compose the message using fields like `data.lead.firstName`, `data.lead.companyName`, and `data.campaign.name` (e.g., "New reply from Jane at Acme Corp in Q1 Outreach campaign"). 4. In Bearconnect, enable the **Message Replied** event on the campaign mapping. ### Add leads to email sequences on connection acceptance 1. Create a Zap with a Catch Hook trigger. 2. Add an action for your email tool (e.g., "Mailchimp - Add Subscriber", "Lemlist - Add Lead to Sequence"). 3. Map `data.lead.email`, `data.lead.firstName`, and `data.lead.lastName` to the required fields. 4. In Bearconnect, enable the **Connection Accepted** event on the campaign mapping. ### Track outreach activity in a spreadsheet for reporting 1. Create a Zap with a Catch Hook trigger. 2. Add a "Google Sheets - Create Spreadsheet Row" action. 3. Map `event` (the event type), `timestamp`, `data.lead.firstName`, `data.lead.lastName`, `data.lead.companyName`, `data.lead.position`, and `data.campaign.name` to columns. 4. Enable **all 4 events** on the campaign mapping to capture the full outreach timeline. 5. Use the spreadsheet to build dashboards or share outreach progress with your team. ### Update CRM deal stage when leads reply 1. Create a Zap with a Catch Hook trigger. 2. Add a Filter step: only continue if `event` equals `message_replied`. 3. Add a "[HubSpot](https://bearconnect.io/docs/integrations/hubspot/) - Update Deal" or "[Pipedrive](https://bearconnect.io/docs/integrations/pipedrive/) - Update Deal" action. 4. Use `data.lead.email` to find the existing deal and update its stage to "Contacted" or "Replied". 5. In Bearconnect, enable the **Message Replied** event on the campaign mapping. --- ## Troubleshooting ### "Test failed" when testing the connection 1. **Check that the URL is correct** - Make sure it is a valid `https://hooks.zapier.com/hooks/catch/...` URL. Bearconnect only accepts HTTPS URLs on the `hooks.zapier.com` domain for Zapier integrations. 2. **Check that the Zap exists** - If you deleted the Zap in Zapier, the Catch Hook URL becomes invalid. 3. **Check the timeout** - If Zapier takes longer than the configured timeout (default 30 seconds) to respond, the delivery is marked as failed. Increase the timeout in Advanced Settings if needed. ### Events not arriving in Zapier 1. **Check that the Zap is turned ON** - A Zap in draft or paused state does not process incoming hooks. 2. **Check the campaign mapping** - Open the campaign's **Integrations** tab and verify that the Zapier integration is connected with the correct events enabled. 3. **Check the toggle switch** - Make sure event forwarding is not paused on the campaign mapping. 4. **Check the integration's allowed events** - The events enabled on the campaign mapping must be a subset of the events allowed on the integration itself. ### "Hook URL not configured" error This means the Catch Hook URL was not saved correctly. Edit the Zapier integration in Bearconnect, re-paste the URL, and save. ### Wrong data structure or missing fields in Zap If the fields in your Zap's action steps do not match what you expect: 1. Go to **Integrations** in Bearconnect and click **Test Connection** on your Zapier integration to send a fresh sample payload. 2. In Zapier, go to the Catch Hook trigger step and click **Test trigger** to re-detect the data structure. 3. Zapier will pick up the latest payload and update the available fields. ### Deliveries showing as "failed" with retries Bearconnect automatically retries failed deliveries with exponential backoff (3 attempts by default, handled by the BullMQ queue). If all retries fail, the delivery is marked as permanently failed and the error count increases on the integration's status. Common causes: - Zapier temporarily unavailable. - Catch Hook URL invalidated (Zap deleted or reconfigured). - Zapier rate limiting on your account. 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. --- # Make (Integromat) Integration Guide Make (formerly Integromat) lets you connect Bearconnect to thousands of apps without writing code. Whenever a lead accepts a connection, a message is sent, or another tracked event occurs, Bearconnect sends a JSON payload to your Make Custom Webhook URL, which triggers a Make scenario. This is ideal for routing leads to CRMs, enriching contact data, sending notifications, and building multi-step automation workflows. --- ## Table of Contents 1. [What You Need](#what-you-need) 2. [Setting Up the Make Webhook](#setting-up-the-make-webhook) 3. [Connecting Make in Bearconnect](#connecting-make-in-bearconnect) 4. [After Connecting](#after-connecting) 5. [Connecting Make to a Campaign](#connecting-make-to-a-campaign) 6. [Exporting Leads via Make](#exporting-leads-via-make) 7. [Payload Format](#payload-format) 8. [Testing Your Connection](#testing-your-connection) 9. [Working with Data in Make](#working-with-data-in-make) 10. [Use Cases](#use-cases) 11. [Managing Your Make Integration](#managing-your-make-integration) 12. [Troubleshooting](#troubleshooting) --- ## Quick Start Already familiar with Make? Here is the fastest path: 1. In Make: Create a scenario with **Webhooks > Custom webhook** trigger. Copy the webhook URL. 2. **Toggle the scenario ON** (this is required - inactive scenarios reject events). 3. In Bearconnect: Go to **Integrations > Make > Connect**. Paste the URL, select events, click **Connect**. 4. In Bearconnect: Click **Test Connection** to send sample data and trigger Make's data structure detection. 5. In Bearconnect: Open a campaign > **Integrations** tab > **Connect Integration** > select your Make integration and enable events. 6. In Make: Add modules after the webhook trigger and use the mapping panel to reference Bearconnect fields. --- ## What You Need - A **Bearconnect account** with an active subscription. - A **Make account** (Free or paid plan). - A Make scenario with a **[Custom Webhook](https://www.make.com/en/help/tools/webhooks)** module as the trigger. --- ## Setting Up the Make Webhook Before connecting in Bearconnect, you need to create a Custom Webhook in Make to get a URL. 1. Log in to your **Make** account at [make.com](https://www.make.com). 2. Click **Create a new scenario**. 3. Click the **+** button to add the first module. 4. Search for **Webhooks** and select the **Webhooks** app. 5. Choose **Custom webhook** as the trigger type. 6. Click **Add** to create a new webhook. Give it a name (e.g., "Bearconnect Events"). 7. Click **Save**. 8. Make displays a URL in the format `https://hook.{region}.make.com/...` - copy this URL. 9. **Toggle the scenario ON** using the switch at the bottom of the scenario editor. > **Important:** The webhook URL must be on `hook.*.make.com` and must use HTTPS. Bearconnect will > not accept URLs that do not match this pattern. > **Important:** The scenario must be toggled **ON** for Bearconnect to deliver events. If the > scenario is inactive, Make returns a 400 error and deliveries will fail. --- ## Connecting Make in Bearconnect 1. Go to **Integrations** in the left sidebar of your Bearconnect dashboard. 2. Find **Make** in the Available Integrations section and click **Connect**. 3. A dialog opens with the following fields: ### Required Fields | Field | Description | | ---------------------- | ----------------------------------------------------------------------------- | | **Name** | A label to identify this connection (e.g., "Make - Lead Routing"). | | **Custom Webhook URL** | The webhook URL you copied from Make (must be `https://hook.*.make.com/...`). | ### 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 Make (e.g., `X-Source: bearconnect`). | | **Timeout (ms)** | 30000 | 5000–60000 | How long to wait for Make to respond before marking the delivery as failed. | 4. Click **Connect**. --- ## After Connecting Your Make integration now appears in the **Connected Integrations** section. Click on it to open the detail panel, which shows: ### Webhook URL Your configured Make 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 (Make). - Integration ID. - Last updated timestamp. --- ## Connecting Make to a Campaign To receive events from a specific campaign, you must map the Make integration to that campaign. 1. Open a campaign from your dashboard. 2. Go to the **Integrations** tab. 3. Click **Connect Integration**. 4. Select your Make integration from the dropdown. 5. Choose which events to enable for this campaign (only events that are in the integration's allowed events list appear here). 6. 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 Make integration itself is not deleted). --- ## Exporting Leads via Make You can manually export a lead to Make. 1. Go to the **Leads** page. 2. Find the lead you want to export and click the **three-dot action menu** on that row. 3. Click **Export**. 4. Select your Make integration from the dropdown. 5. Click **Export**. The lead data is sent immediately as a JSON payload to your Make webhook URL, which triggers the scenario. --- ## Payload Format Every delivery to Make is an HTTP POST request with a JSON body. The payload format is identical to Custom Webhooks - all integration providers receive the exact same structure. ### Event Payload ```json { "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 Make, use the `ifempty()` function in field mappings to provide fallback values for > nullable fields. For example: `{{ifempty(1.data.lead.email; "no-email@placeholder.com")}}`. ### 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 Make includes: | Header | Value | | -------------- | ------------------------------------------------ | | `Content-Type` | `application/json` | | `User-Agent` | `Bearconnect/1.0` | | Custom headers | Any headers you configured in Advanced Settings. | --- ## Testing Your Connection Testing serves two purposes: it verifies that Bearconnect can reach your Make webhook, and it triggers Make's **data structure detection** so Make knows the shape of the incoming data. 1. Go to **Integrations** in the left sidebar. 2. Click on your Make integration to open the detail panel. 3. Click **Test Connection**. 4. If successful, you will see "Test successful" with the HTTP status code (e.g., 200). 5. If it fails, the error message will indicate the problem (timeout, connection refused, non-2xx status code, etc.). The test sends a real payload to your Make webhook. After a successful test, go back to Make - the Custom Webhook module will show "Successfully determined" with the detected data structure. This allows you to use the mapping panel in subsequent modules. > **Tip:** If you add the Make integration and skip the test, Make will not know the data structure. > You can still run the scenario, but the mapping panel will be empty until Make receives at least > one request. --- ## Working with Data in Make ### Data Structure Detection After the first successful test or live event, Make automatically detects the payload structure. You will see this in the Custom Webhook module as "Successfully determined." From that point on, all fields are available in the mapping panel of subsequent modules. ### Referencing Fields in Modules In any module after the Custom Webhook trigger, use the mapping panel to select fields. The fields follow the payload structure: | Make Field Path | Example Value | | ---------------------------- | --------------------------------------- | | `event` | `connection_request_accepted` | | `timestamp` | `2026-02-13T10:30:00.000Z` | | `data.lead.firstName` | `Jane` | | `data.lead.lastName` | `Smith` | | `data.lead.email` | `jane.smith@example.com` | | `data.lead.companyName` | `Acme Corp` | | `data.lead.profileUrl` | `https://www.linkedin.com/in/janesmith` | | `data.lead.profileHeadline` | `VP of Sales at Acme Corp` | | `data.lead.position` | `VP of Sales` | | `data.lead.location` | `San Francisco, CA` | | `data.lead.stage` | `connected` | | `data.campaign.name` | `Q1 Outreach` | | `data.campaign.status` | `running` | | `data.linkedInAccount.name` | `Sales Team Account` | | `data.linkedInAccount.email` | `john.smith@example.com` | | `metadata.eventId` | `evt_abc123def456` | ### Using Routers and Filters Make's **Router** module lets you send data down different paths based on conditions. For example: - Route `connection_request_accepted` events to a CRM module. - Route `message_replied` events to a Slack notification module. - Filter by `data.campaign.name` to handle different campaigns differently. --- ## Use Cases ### Route Leads to Different CRMs by Campaign Use a Router module after the Custom Webhook trigger. Add a filter on each path that checks `data.campaign.name`, then connect each path to the appropriate CRM module ([HubSpot](https://bearconnect.io/docs/integrations/hubspot/), Salesforce, [Pipedrive](https://bearconnect.io/docs/integrations/pipedrive/), etc.). ### Enrich Leads Before Adding to CRM Chain modules in sequence: Custom Webhook trigger, then a Clearbit or Apollo enrichment module using `data.lead.email`, then a CRM module that combines the Bearconnect data with the enriched data. ### Send Slack Notifications When Leads Reply Add a filter after the Custom Webhook trigger that checks for `event` equals `message_replied`. Connect it to a Slack module that posts a message like: "Jane Smith from Acme Corp replied to your Q1 Outreach campaign." ### Multi-Step Workflows Build scenarios that react to sequential events. For example: when a connection is accepted, add the lead to a Google Sheet. When a message reply comes in later, update the same row and send a Slack notification to the sales team. ### Visual Lead Qualification Pipeline Take advantage of Make's visual scenario builder to create a qualification pipeline: 1. Custom Webhook trigger receives a Connection Accepted event. 2. Router module splits the flow by `data.lead.companyName` or `data.lead.position`. 3. Path A: Enterprise leads (VP, Director, C-level in title) go to your CRM with a "High Priority" tag. 4. Path B: All other leads go to a Google Sheet for batch review. 5. Add a Slack notification on Path A so your sales team is alerted immediately. This visual approach makes it easy to adjust routing rules without writing code. --- ## Managing Your Make Integration ### Editing the Integration To change the name, URL, events, or other settings: 1. Go to **Integrations** in the left sidebar. 2. Click on the Make integration you want to edit. 3. Make your changes in the detail panel. 4. Save. ### Deleting the Integration 1. Go to **Integrations** in the left sidebar. 2. Click on the Make integration you want to delete. 3. Click **Delete** and confirm. When you delete a Make integration: - All campaign mappings using it are removed. - Event forwarding stops immediately. - Delivery history is no longer tracked. --- ## Troubleshooting ### "Make webhook expired (410)" Make webhook URLs expire after **5 days of inactivity**. When this happens, Make returns a 410 Gone response and deliveries fail. **To fix:** 1. Open your scenario in Make. 2. Click on the Custom Webhook module. 3. The webhook may show as expired. Click to re-enable it or create a new webhook. 4. If the URL changed, update it in the Bearconnect integration settings. 5. Toggle the scenario back ON. ### "Make scenario is inactive (400)" Make returns a 400 error when the scenario is not running. **To fix:** 1. Open your scenario in Make. 2. Toggle the scenario **ON** using the switch at the bottom of the scenario editor. ### "Test failed" or connection errors 1. **Check the URL format** - The URL must start with `https://hook.` and be on a `make.com` domain (e.g., `https://hook.us1.make.com/...`). 2. **Check that the scenario is ON** - Make rejects requests to inactive scenarios. 3. **Check the webhook is not expired** - If the webhook has been inactive for more than 5 days, it may have expired. Re-open the scenario to refresh it. ### Data not appearing in Make If events are delivered successfully (you can see the delivery count increasing in Bearconnect) but Make is not showing the data: 1. **Re-run the test** - Go to the Make integration in Bearconnect and click **Test Connection**. This triggers Make's data structure detection. 2. **Check the scenario execution history** - In Make, click the clock icon to view execution history. Look for any errors. 3. **Check that the webhook module is the trigger** - The Custom Webhook module must be the first module in the scenario. ### Events not arriving 1. **Check campaign mapping** - Open the campaign's **Integrations** tab and verify that the Make integration is connected and the toggle is enabled. 2. **Check the event selection** - Verify that the events you expect are enabled both on the integration and on the campaign mapping. 3. **Check the scenario is ON** - If the scenario is inactive, Make returns an error and Bearconnect marks the delivery as failed. ### Rate limiting Make allows **300 requests per 10 seconds** per scenario. If your Bearconnect campaigns generate events faster than this, some deliveries may be throttled. To mitigate this: - Spread events across multiple scenarios with different webhook URLs. - Reduce the number of events forwarded by selecting only the events you need. ### "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. --- # 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. --- ## Table of Contents 1. [What You Need](#what-you-need) 2. [Production URL vs Test URL](#production-url-vs-test-url) 3. [Connecting n8n to Bearconnect](#connecting-n8n-to-bearconnect) 4. [After Connecting](#after-connecting) 5. [Connecting n8n to a Campaign](#connecting-n8n-to-a-campaign) 6. [Exporting Leads via n8n](#exporting-leads-via-n8n) 7. [Payload Format](#payload-format) 8. [Working with Payloads in n8n](#working-with-payloads-in-n8n) 9. [Testing Your Connection](#testing-your-connection) 10. [Managing Your n8n Integration](#managing-your-n8n-integration) 11. [Use Cases](#use-cases) 12. [Troubleshooting](#troubleshooting) --- ## Quick Start Already familiar with n8n? Here is the fastest path: 1. In n8n: Create a workflow with a **Webhook** trigger node. Switch to the **Production** tab and copy the Production URL. 2. **Activate the workflow** (inactive workflows return 404 on the Production URL). 3. In Bearconnect: Go to **Integrations > n8n > Connect**. Paste the Production URL, configure authentication if needed, select events, click **Connect**. 4. In Bearconnect: Click **Test Connection** to verify the webhook is reachable. 5. 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](https://docs.n8n.io/hosting/)** (cloud or self-hosted) accessible over HTTPS. - An **n8n workflow** with a **[Webhook trigger node](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/)** 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 1. Open your workflow in the n8n editor. 2. Click on the **Webhook** trigger node. 3. In the node settings panel, switch to the **Production** tab. 4. Copy the Production URL. --- ## Connecting n8n to Bearconnect 1. Go to **Integrations** in the left sidebar of your Bearconnect dashboard. 2. Find **n8n** in the Available Integrations section and click **Connect**. 3. 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: ` 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. | 4. 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. 1. Open a campaign from your dashboard. 2. Go to the **Integrations** tab. 3. Click **Connect Integration**. 4. Select your n8n integration from the dropdown. 5. Choose which events to enable for this campaign (only events that are in the integration's allowed events list appear here). 6. 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. 1. Go to the **Leads** page. 2. Find the lead you want to export and click the **three-dot action menu** (⋮) on that row. 3. Click **Export**. 4. Select your n8n integration from the dropdown. 5. 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 ```json { "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. 1. Go to **Integrations** in the left sidebar. 2. Click on your n8n integration to open the detail panel. 3. Click **Test Connection**. 4. If successful, you will see "Test successful" with the HTTP status code (e.g., 200). 5. 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: 1. Go to **Integrations** in the left sidebar. 2. Click on the n8n integration you want to edit. 3. Make your changes in the detail panel. 4. Save. ### Deleting the Integration 1. Go to **Integrations** in the left sidebar. 2. Click on the n8n integration you want to delete. 3. 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](#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](https://bearconnect.io/docs/integrations/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)" 1. **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. 2. **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)" 1. **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. 2. **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: 1. Open your workflow in the n8n editor. 2. Click on the Webhook trigger node. 3. Switch to the **Production** tab. 4. Copy the Production URL (it will contain `/webhook/` instead of `/webhook-test/`). 5. Paste the Production URL into Bearconnect. ### Events not arriving in n8n 1. **Check that the workflow is active** - Inactive workflows do not receive events on the Production URL. 2. **Check campaign mapping** - Open the campaign's Integrations tab and verify the n8n integration is connected and the toggle is enabled. 3. **Check event selection** - Verify the events you expect are enabled both on the integration (in Integrations settings) and on the campaign mapping. 4. **Check authentication** - If auth credentials do not match, n8n will reject the request silently or return a 401. 5. **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. --- # Custom Webhook Integration Guide Custom webhooks let you send Bearconnect events to any HTTP endpoint in real time. Whenever a lead accepts a connection, a message is sent, or another tracked event occurs, Bearconnect sends a JSON payload to your configured URL. This is ideal for connecting to internal tools, automation platforms, or any system that can receive HTTP POST requests. --- ## Table of Contents 1. [What You Need](#what-you-need) 2. [Creating a Webhook](#creating-a-webhook) 3. [After Creating](#after-creating) 4. [Connecting a Webhook to a Campaign](#connecting-a-webhook-to-a-campaign) 5. [Exporting Leads via Webhook](#exporting-leads-via-webhook) 6. [Webhook Payload Format](#webhook-payload-format) 7. [Verifying Webhook Signatures](#verifying-webhook-signatures) 8. [Testing Your Webhook](#testing-your-webhook) 9. [Managing Webhooks](#managing-webhooks) 10. [Troubleshooting](#troubleshooting) --- ## Quick Start Already have an HTTPS endpoint ready? Here is the fastest path: 1. In Bearconnect: Go to **Integrations > Custom Webhooks > Connect**. 2. Enter a name, paste your endpoint URL, select events, click **Create Webhook**. 3. If you enabled HMAC signatures, copy the signing secret immediately (it is only shown once). 4. Click **Test Webhook** on your new webhook to verify delivery. 5. Open a campaign > **Integrations** tab > **Connect Integration** > select your webhook and enable events. --- ## What You Need - A **Bearconnect account** with an active subscription. - An **HTTP endpoint** that can receive POST requests with JSON bodies. - (Optional) The ability to verify HMAC-SHA256 signatures on your server if you want payload security. --- ## Creating a Webhook 1. Go to **Integrations** in the left sidebar of your Bearconnect dashboard. 2. Find **Custom Webhooks** in the Available Integrations section and click **Connect**. 3. A dialog opens with the following fields: ### Required Fields | Field | Description | | ---------------- | --------------------------------------------------------------------------- | | **Name** | A label to identify this webhook (e.g., "CRM Sync", "Slack Notifier"). | | **Endpoint URL** | The full URL that will receive event payloads (must start with `https://`). | ### Optional: HMAC Signature Toggle **HMAC Signature** on if you want Bearconnect to sign every payload. When enabled: - Bearconnect generates a signing secret for you. - Each request includes a signature header that your server can use to verify the payload is authentic. - See [Verifying Webhook Signatures](#verifying-webhook-signatures) for implementation details. ### Event Selection Choose which event types this webhook 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 webhook request (e.g., `Authorization: Bearer your-token`). | | **Max Retries** | 3 | 1–5 | How many times Bearconnect retries a failed delivery before giving up. | | **Timeout (ms)** | 30000 | 5000–60000 | How long to wait for your server to respond before marking the delivery as failed. | 4. Click **Create Webhook**. --- ## After Creating Your webhook now appears in the **Connected Integrations** section. Click on it to open the detail panel, which shows: ### Webhook URL Your configured endpoint URL is displayed and can be copied with the copy button. ### Signing Secret If HMAC signatures are enabled: - Click the **eye icon** to reveal the signing secret (fetched securely on demand). - Click **Copy** to copy the secret to your clipboard. - Click **Regenerate Secret** to generate a new secret. This immediately invalidates the old secret - update your server before regenerating. If HMAC signatures are disabled, the section shows "Signature verification is disabled." ### 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 webhook is configured to handle, organized by category. ### Connection Details - When the webhook was created. - Provider type (Webhook). - Integration ID. - Last updated timestamp. --- ## Connecting a Webhook to a Campaign To receive events from a specific campaign, you must map the webhook to that campaign. 1. Open a campaign from your dashboard. 2. Go to the **Integrations** tab. 3. Click **Connect Integration**. 4. Select your webhook from the dropdown. 5. Choose which events to enable for this campaign (only events that are in the webhook's allowed events list appear here). 6. 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 webhook itself is not deleted). --- ## Exporting Leads via Webhook You can manually export a lead to a webhook. 1. Go to the **Leads** page. 2. Find the lead you want to export and click the **three-dot action menu** (⋮) on that row. 3. Click **Export**. 4. Select your webhook from the dropdown. 5. Click **Export**. Unlike [HubSpot](https://bearconnect.io/docs/integrations/hubspot/), there is no field mapping step - the lead data is sent immediately as a JSON payload to your webhook URL. --- ## Webhook Payload Format Every webhook delivery is an HTTP POST request with a JSON body. Here is the structure: ### Event Payload This is the universal payload format used by Custom Webhooks, [Zapier](https://bearconnect.io/docs/integrations/zapier/), [Make](https://bearconnect.io/docs/integrations/make/), and [n8n](https://bearconnect.io/docs/integrations/n8n/). All providers receive the exact same structure. ```json { "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 (e.g., `janesmith`). 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 (e.g., `connected`, `replied`). May be `null`. | | `data.lead.createdAt` | No | ISO timestamp of when the lead was added. May be `null`. | | `data.campaign` | No | May be absent if the event is not campaign-specific. | | `data.campaign.status` | No | May be `null`. | | `data.linkedInAccount` | No | May be absent if no LinkedIn account is associated. | | `data.linkedInAccount.id` | Yes (if present) | Always present when `linkedInAccount` is included. | | `data.linkedInAccount.name` | Yes (if present) | Full name of the LinkedIn account owner. Falls back to "LinkedIn Account" if name is unavailable. | | `data.linkedInAccount.email` | Yes (if present) | Login email of the LinkedIn account used for outreach. Always present when `linkedInAccount` is included. | > **Tip:** When building your integration, always check for `null` or missing fields before using > them. For example, not all leads will have an email address, so do not rely on `data.lead.email` > being present for every event. ### 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 webhook request includes: | Header | Value | | ------------------------- | -------------------------------------------------------------------------------- | | `Content-Type` | `application/json` | | `User-Agent` | `Bearconnect-Webhook/1.0` | | `X-Webhook-Id` | The integration ID for this webhook. | | `X-Bearconnect-Timestamp` | Unix timestamp of when the signature was generated (only if signing is enabled). | | `X-Bearconnect-Signature` | HMAC-SHA256 signature (only if signing is enabled). | | Custom headers | Any headers you configured in Advanced Settings | --- ## Verifying Webhook Signatures If you enabled HMAC signatures, every request includes an `X-Bearconnect-Signature` header. Your server should verify this to confirm the payload is from Bearconnect and has not been tampered with. ### How It Works 1. Bearconnect computes an HMAC-SHA256 hash of the raw request body using your signing secret. 2. The hash is sent in the `X-Bearconnect-Signature` header. 3. Your server computes the same hash and compares it. ### Example: Node.js Verification ```javascript const crypto = require('crypto'); function verifyWebhookSignature(rawBody, signature, secret) { const expectedSignature = crypto.createHmac('sha256', secret).update(rawBody).digest('hex'); // Use timing-safe comparison to prevent timing attacks return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature)); } // In your webhook handler: app.post('/webhook', (req, res) => { const signature = req.headers['x-bearconnect-signature']; const isValid = verifyWebhookSignature(req.rawBody, signature, YOUR_SIGNING_SECRET); if (!isValid) { return res.status(401).json({ error: 'Invalid signature' }); } // Process the webhook... res.status(200).json({ received: true }); }); ``` ### Example: Python Verification ```python import hmac import hashlib def verify_webhook_signature(raw_body: bytes, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode('utf-8'), raw_body, hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected) ``` > **Important:** Always use the raw request body (bytes) for signature verification, not a > parsed/re-serialized JSON object. JSON serialization can change field ordering or whitespace, > which would cause the signature to not match. --- ## Testing Your Webhook You can send a test request to verify your webhook is reachable and responding correctly. 1. Go to **Integrations** in the left sidebar. 2. Click on your webhook to open the detail panel. 3. Click **Test Webhook**. 4. If successful, you will see "Test successful" with the HTTP status code (e.g., 200). 5. 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 endpoint. Your server should respond with a 2xx status code (200, 201, 202, etc.) to indicate success. --- ## Managing Webhooks ### Editing a Webhook To change the name, URL, events, or other settings: 1. Go to **Integrations** in the left sidebar. 2. Click on the webhook you want to edit. 3. Make your changes in the detail panel. 4. Save. ### Regenerating the Signing Secret If your signing secret has been compromised: 1. Open the webhook detail panel. 2. In the **Signing Secret** section, click **Regenerate Secret**. 3. Confirm the action. 4. The old secret stops working immediately. Copy the new secret and update your server. ### Deleting a Webhook 1. Go to **Integrations** in the left sidebar. 2. Click on the webhook you want to delete. 3. Click **Delete** and confirm. When you delete a webhook: - All campaign mappings using it are removed. - Event forwarding stops immediately. - Delivery history is no longer tracked. --- ## Troubleshooting ### "Test failed" or events not being delivered 1. **Check that your URL is correct** - Make sure it is a valid HTTPS URL and is publicly accessible (not behind a firewall or VPN without proper routing). 2. **Check your server is running** - Try hitting the URL directly with a tool like `curl` to confirm it responds. 3. **Check the response code** - Bearconnect expects a 2xx status code. If your server returns 4xx or 5xx, the delivery is marked as failed. 4. **Check the timeout** - If your server takes longer than the configured timeout (default 30 seconds) to respond, the delivery is marked as failed. Increase the timeout in Advanced Settings if needed. ### Signature verification failing 1. **Use the raw body** - Verify against the raw request body bytes, not a parsed JSON string. 2. **Check the secret** - Make sure you are using the current signing secret. If you regenerated it, the old secret no longer works. 3. **Check the header name** - The signature is in the `X-Bearconnect-Signature` header (case-insensitive for HTTP headers). The timestamp is in `X-Bearconnect-Timestamp`. ### Events arriving for wrong event types Check the mapping configuration: 1. Open the campaign's **Integrations** tab. 2. Click the settings icon on the webhook mapping. 3. Verify that only the desired events are enabled. Remember: the webhook's **allowed events** (set when creating the webhook) determine the maximum set of events. The campaign mapping's **enabled events** must be a subset of those. ### Deliveries showing as "failed" with retries Bearconnect automatically retries failed deliveries with exponential backoff. The default is 3 retries. If all retries fail, the delivery is marked as permanently failed and the error count increases on the webhook's status. Common causes: - Server temporarily unavailable. - Rate limiting on your endpoint. - Server returning non-2xx responses. Check the error message in the webhook 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 webhook or HubSpot connection first.