Webhooks

What's a webhook?

A webhook is a URL that ConnectSafely calls when something happens — instead of your code having to keep asking "anything new yet?".

When a LinkedIn message lands on one of your connected accounts, ConnectSafely sends an HTTP POST request to a URL you control. The body of that request is JSON that describes the message. You write a small endpoint that receives the POST and does whatever you want with it: store it, reply, ping Slack, hand it to an AI agent.

Status: Webhooks are in Beta. The shape and headers documented here are stable — only new event types may be added.

Why bother?

Without webhooks, you'd have to poll our API every few seconds to see if there's a new message. That's slow, wastes quota, and you'll still miss things.

With a webhook, your code only runs when there's actually something to react to. Common things people build:

• Auto-reply to LinkedIn DMs with an AI assistant
• Route inbound InMail to a Slack channel
• Sync new conversations into a CRM (HubSpot, Salesforce, etc.)
• Trigger downstream automations in n8n, Make.com, or Zapier

Before you start

You'll need:

1. An active ConnectSafely API subscription on the LinkedIn account you want events from. Non-API seats can't subscribe to message webhooks.
2. A public HTTPS URL that can accept POST requests and reply with 2xx in under 15 seconds.

New to this? While developing locally, use ngrok or Cloudflare Tunnel to expose localhost to the public internet temporarily.

The simplest possible receiver

Here's a Node.js / Express server that just logs every event it gets:

import express from "express";
const app = express();

app.post("/webhook", express.json(), (req, res) => {
  console.log("Got event:", req.body.event);
  console.log("From:", req.body.data.sender.name);
  console.log("Body:", req.body.data.body);
  res.sendStatus(200); // <- tell ConnectSafely we got it
});

app.listen(3000, () => console.log("Listening on :3000"));

That's it. Not safe for production — anyone who guesses your URL can fake events. We fix that on the Security & auth page. For now, this is enough to see real events flowing.

Quick start

1. Create a webhook in the dashboard

Open the Webhooks dashboard and click Create Webhook:

1. Name — anything that helps you find it later in logs (e.g. Lead → CRM).
2. URL — your public HTTPS endpoint (the one ngrok / your server gives you).
3. Event — pick message.received. That covers regular DMs and InMail.
4. LinkedIn account — pick a specific account, or leave blank to subscribe to every account in your workspace.
5. (Optional) Auth header — extra security if your endpoint already expects an Authorization header. See Security & auth.
6. Save. ConnectSafely shows you a signing secret one time only — copy it now into a password manager or env var. You'll need it to verify incoming events.

2. Send a test event

On the webhook row, click Test. ConnectSafely sends a fake-but-realistic message.received payload to your URL and shows you the status code and round-trip time inline. If you don't get a 200 back, the Logs button on the same row tells you why.

3. Wait for a real message

Send yourself a LinkedIn message from another account. Within a couple of seconds you should see the event hit your endpoint. 🎉

Supported events

More events will appear in the dashboard as we ship them.

What to read next