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
2. Creating a Webhook
3. After Creating
4. Connecting a Webhook to a Campaign
5. Exporting Leads via Webhook
6. Webhook Payload Format
7. Verifying Webhook Signatures
8. Testing Your Webhook
9. Managing Webhooks
10. 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 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, 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, Make, and n8n. All providers receive the exact same structure.

{
    "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

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

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.