Webhooks Introduction

Webhooks allow you to receive real-time notifications when events happen on your connected accounts — new messages, connection acceptances, incoming connection requests, and more.

Delivery Modes

Webhooks support two delivery modes depending on your setup:

Hosted Mode

No server needed. Events are delivered via SSE stream or polling. Perfect for bots, scripts, and local apps.Create a webhook without a url to use hosted mode.

Custom Mode

Events are sent as POST requests to your server. Requires a publicly accessible HTTPS endpoint.Create a webhook with a url to use custom mode.

	Hosted	Custom
Setup	No server required	HTTPS endpoint required
Real-time delivery	SSE stream (`GET /stream`)	HTTP POST to your URL
Delivery guarantee	Pull at your pace	At-least-once: retries with backoff, delivery log, replay
Event history	30 days stored events (`GET /events`)	30 days stored events (`GET /events`) + replay
Best for	Bots, scripts, local dev	Production servers

Custom mode supports optional HMAC-SHA256 signature verification so your server can reject spoofed payloads. Opt in with enable_signature: true at creation time.

Delivery & retries (custom mode)

Custom webhooks are delivered at least once. Every envelope carries a stable top-level event_id (also sent as X-Linkup-Event-Id, with X-Linkup-Attempt) — dedupe on it. A POST is successful on any 2xx. On timeout (10 s), connection error, 5xx, 408/425/429 we retry with backoff: 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h (8 attempts). Any other 4xx or a 3xx is recorded as failed and not retried. Turn retries off per webhook with retry: false. Everything we sent, or still owe, is visible for 30 days, and replayable, from the API:

Endpoint	Purpose
`GET /v2/webhooks/{id}/deliveries?state=failed`	Delivery log: each attempt, the status code you returned, timeouts, next retry (`cursor` paging, `since`/`until`, `event_id`)
`GET /v2/webhooks/{id}/deliveries/{delivery_id}`	One delivery with the exact payload we POSTed
`POST /v2/webhooks/{id}/deliveries/{delivery_id}/replay`	Re-POST it now (header `X-Linkup-Replay: true`)
`POST /v2/webhooks/{id}/replay`	`{"event_id": "…"}` re-POSTs one event now; `{"from": "…", "to": "…", "only_failed": true}` queues a time range (max 5000)
`GET /v2/webhooks/{id}/events?after=<event_id>`	Pull the stored events yourself (30 days), no LinkedIn traffic
`GET /v2/webhooks/retry-policy`	The policy above, as data

How It Works

Hosted Mode
Custom Mode

Connect your account

Use POST /v2/login to connect an account and get an account_id.

Create a hosted webhook

Call POST /v2/webhooks without a url. You’ll receive a webhook_id, stream_url, and events_url. Monitoring starts automatically.

Receive events

Connect to the SSE stream or poll the events endpoint.

Connect your account

Use POST /v2/login to connect an account and get an account_id.

Create a webhook with URL

Call POST /v2/webhooks with your server’s url. Monitoring starts automatically.

Receive events

Events are sent as POST requests to your URL in real time.

Event Types

Subscription filter	Emitted `event.type`	Description
`message_received`	`"message"`	A new message (LinkedIn) or email was received — use the top-level `platform` field to tell the two channels apart
`accepted_invitation`	`"accepted_invitation"`	One or more connection requests you sent were accepted
`invitation_received`	`"invitation_received"`	The account received one or more new connection requests
`email_bounced` (email, via `all`)	`"email_bounced"`	An email you sent bounced
`all`	—	Subscribe to all event types

By default, webhooks listen to all event types. In custom mode, you can filter specific events when creating the webhook by passing an events array. Hosted webhooks (SSE stream and GET /events) always receive every event type — only the message_type direction filter applies — so filter on event.type on your side.

The subscription filter message_received is intentionally different from the actual event.type, which is "message". Filter against message_received when creating the webhook. A LinkedIn message and an inbound email both arrive as event.type === "message" — read the top-level platform field ("linkedin" vs "email") to tell them apart (see Email events).

In addition to subscribed events, every webhook also receives disconnection events — this is not filterable. They fire whenever the underlying platform session expires so you can react (re-auth, alert, etc.).

Event Payload Format

All events share the same wrapper structure. Note that the outer timestamp is when the API emitted the event, while event.timestamp is when the underlying platform activity happened — they differ slightly (latency). The top-level platform field ("linkedin", "email" or "whatsapp") tells you which channel the event came from — this is how you distinguish an inbound email from a LinkedIn DM, since both use event.type: "message". The top-level event_id is the stable identifier of the event: identical on every retry or replay, and the key to dedupe on (see Delivery & retries).

{
  "event_id": "6ab13cf890294b92776b5343",
  "account_id": "69ee261e41fc4cbecf9f34c9",
  "account_name": "[email protected]",
  "platform": "linkedin",
  "event": {
    "type": "...",
    "timestamp": "2026-04-28T08:07:45.525693"
    // event-specific fields below
  },
  "timestamp": "2026-04-28T08:07:45.525853"
}

Message Received

Triggered in real-time when a new message is received via the platform’s realtime stream (sub-second latency). The inner event type is "message" and platform is "linkedin".

{
  "account_id": "69ee261e41fc4cbecf9f34c9",
  "account_name": "[email protected]",
  "platform": "linkedin",
  "event": {
    "type": "message",
    "inbox": "classic",
    "timestamp": "2026-04-28T10:07:45.525693",
    "message_text": "Hello! I'd love to connect.",
    "sender": {
      "name": "John Doe",
      "profile_url": "https://www.linkedin.com/in/ACoAAEMT_nsB5U1uon01_EjK9Yf4En52jDd2hGE"
    },
    "conversation": {
      "participants": [
        {
          "name": "Your Name",
          "profile_url": "https://www.linkedin.com/in/ACoAADxnv0oB_dN-NfpvEBlsVPU_W1omM-Xu24o"
        },
        {
          "name": "John Doe",
          "profile_url": "https://www.linkedin.com/in/ACoAAEMT_nsB5U1uon01_EjK9Yf4En52jDd2hGE"
        }
      ],
      "is_group_chat": false,
      "unread_count": 1
    },
    "metadata": {
      "entity_urn": "urn:li:msg_message:(urn:li:fsd_profile:ACoAADxnv0oB_dN-NfpvEBlsVPU_W1omM-Xu24o,2-MTc3NzM2MzY2NDkyMGI4MzE3Mi0xMDAmMDZiY2ExOTgtM2NjNy00OTU4LTgyNjUtZWFlMmIwZjM1NTlmXzEwMA==)",
      "conversation_urn": "urn:li:msg_conversation:(urn:li:fsd_profile:ACoAADxnv0oB_dN-NfpvEBlsVPU_W1omM-Xu24o,2-MDZiY2ExOTgtM2NjNy00OTU4LTgyNjUtZWFlMmIwZjM1NTlmXzEwMA==)",
      "delivered_at": 1777363664920,
      "read_status": false
    }
  },
  "timestamp": "2026-04-28T08:07:45.525853"
}

Field reference

Field	Type	Description
`event.inbox`	`string`	Which inbox the message came from: `classic` for LinkedIn messaging, `sales_navigator` for a Sales Navigator InMail thread. See Sales Navigator inbox.
`event.message_text`	`string`	Plain text content of the message
`event.sender.name`	`string`	Display name of the sender
`event.sender.profile_url`	`string`	Profile URL of the sender (ID-based, not vanity)
`event.conversation.participants`	`array`	All participants of the thread, sender included
`event.conversation.is_group_chat`	`boolean`	`true` if 3+ participants
`event.conversation.unread_count`	`integer`	Number of unread messages in the thread
`event.reply_to`	`object?`	Only present when the message is a reply. Contains `message_text`, `sender_name`, `sender_profile_url`, `timestamp` of the original message. Omitted (not `null`) for non-reply messages.
`event.metadata.entity_urn`	`string`	Unique identifier of the message
`event.metadata.conversation_urn`	`string`	Unique identifier of the conversation thread
`event.metadata.delivered_at`	`integer`	Unix milliseconds delivery time
`event.metadata.read_status`	`boolean`	Whether the conversation is marked read
`event.has_attachments`	`boolean`	`true` when the message carries at least one attachment
`event.attachments`	`array`	One entry per attachment. Empty when there are none.
`event.message_type`	`string`	What the message is. Classic inbox: `TEXT`, `MEDIA` (attachment without text) or `SYSTEM`. Sales Navigator inbox: `INMAIL`, `MESSAGE`, `INMAIL_DECLINE` or `INMAIL_ACCEPT`. An `INMAIL_DECLINE` is the prospect pressing “Not interested” on your InMail: it arrives with an empty `message_text` and is a refusal, not a reply.

When the message is a reply, an additional event.reply_to object is included with the original message details. For non-reply messages, the field is omitted entirely from the payload — don’t expect a null.

Attachments

"has_attachments": true,
"attachments": [
  {
    "type": "file",
    "name": "proposal.pdf",
    "mime_type": "application/pdf",
    "byte_size": 184320,
    "asset_urn": "urn:li:digitalmediaAsset:D4E06AQ...",
    "url": "https://media.licdn.com/dms/document/...",
    "download_url": "https://api.linkupapi.com/v2/messages/attachment?account_id=...&conversation_id=...&asset_urn=..."
  }
]

type is image, file, audio, video, gif or unknown. Audio and video also carry duration_ms and thumbnail_url.

url is LinkedIn’s own media URL: it requires the account session and its signature expires, so it is not fetchable on its own. Use download_url — see Download Attachment.

Email events

For an email mailbox, the monitor polls the inbox and emits two event types. Both are covered by the message_received filter / all. Email events carry the top-level platform: "email" — that, not event.type, is how you tell them from a LinkedIn DM. New email received — inner type is "message" (same as a LinkedIn message; platform is what distinguishes them):

{
  "account_id": "6a75f0923a25191f7c8c5bba",
  "account_name": "[email protected]",
  "platform": "email",
  "event": {
    "type": "message",
    "timestamp": "2026-09-14T10:07:45.525693",
    "subject": "Re: Quick question",
    "message_id": "<[email protected]>",
    "in_reply_to": "<[email protected]>",
    "sender": { "name": "John Doe", "email": "[email protected]", "is_self_sent": false },
    "message_text": "Sure, let's chat Thursday.",
    "raw_data": { "entityUrn": "email:[email protected]:<[email protected]>" }
  },
  "timestamp": "2026-09-14T10:07:46.001000"
}

Sent email bounced — inner type is "email_bounced":

{
  "account_id": "6a75f0923a25191f7c8c5bba",
  "account_name": "[email protected]",
  "platform": "email",
  "event": {
    "type": "email_bounced",
    "timestamp": "2026-09-14T10:10:00.000000",
    "subject": "Quick question",
    "message_id": "<[email protected]>",
    "sender": { "name": "Mail Delivery Subsystem", "email": "[email protected]", "is_self_sent": false },
    "bounce_status": "5.1.1",
    "bounce_kind": "hard",
    "bounced_recipient": "[email protected]",
    "raw_data": { "entityUrn": "email:[email protected]:<[email protected]>" }
  },
  "timestamp": "2026-09-14T10:10:01.000000"
}

Field reference

Field	Type	Description
`event.subject`	`string`	Email subject.
`event.message_id`	`string`	The email’s Message-ID.
`event.in_reply_to`	`string?`	Message-ID this email replies to, when it is a reply.
`event.sender.name` / `event.sender.email`	`string`	Sender display name and address.
`event.sender.is_self_sent`	`boolean`	`true` when the mailbox is also the sender.
`event.message_text`	`string`	Snippet of the body (up to 500 chars). Inbound email (`type: "message"`) only.
`event.opt_out_detected`	`boolean?`	Present and `true` when the body/subject looks like an unsubscribe/opt-out.
`event.bounce_status`	`string`	RFC 3463 status code (e.g. `5.1.1`). `email_bounced` only.
`event.bounce_kind`	`string`	`hard` or `soft`. `email_bounced` only.
`event.bounced_recipient`	`string`	The address that bounced. `email_bounced` only.

Sales Navigator inbox

Sales Navigator has its own inbox, separate from LinkedIn messaging. A reply to an InMail lands there and never appears in the classic thread, so it used to be invisible to webhooks. Both inboxes now feed the same webhook. Use event.inbox to tell them apart.

`event.inbox`	Source
`classic`	LinkedIn messaging
`sales_navigator`	Sales Navigator InMail thread

This is automatic: an account whose Sales Navigator seat is connected starts receiving both. Nothing to configure, and no extra credit is charged. An account without a connected seat is unaffected and keeps receiving classic events only.

{
  "account_id": "69ee261e41fc4cbecf9f34c9",
  "account_name": "[email protected]",
  "platform": "linkedin",
  "event": {
    "type": "message",
    "inbox": "sales_navigator",
    "timestamp": "2026-04-28T10:07:45.525693",
    "message_text": "Thanks for reaching out — happy to talk next week.",
    "message_type": "MESSAGE",
    "sender": {
      "name": "Douglas Collombat",
      "profile_url": "https://www.linkedin.com/in/douglas-collombat-8aa5863a7",
      "member_urn": "urn:li:member:1670586754",
      "degree": 1,
      "urn_raw": "urn:li:fs_salesProfile:(ACwAAGOTIYIBDvlWDchVYxaO35AeIjn5Jr9cW5Y,NAME_SEARCH,1aMb)"
    },
    "metadata": {
      "entity_urn": "urn:li:fs_salesMessage:2-MTc4ODU0NDYyMDY5M2IyNTg3Ny0xMDAmOTI0OTkzYTQt...",
      "conversation_urn": "urn:li:fs_salesMessagingThread:2-OTI0OTkzYTQtZjgwNy00OTJlLWJhY2YtNTMyNGRkNWFlYWIy...",
      "delivered_at": 1788544620693
    }
  },
  "timestamp": "2026-04-28T08:07:45.525853"
}

A prospect can decline an InMail instead of answering it. That comes through as a message event with "message_type": "INMAIL_DECLINE" and an empty message_text. Treat it as a refusal: do not count it as a reply, and stop the sequence.

Identifying the sender The realtime stream only gives the sender’s Sales Navigator id, which is meaningless outside Sales Navigator. We resolve it for you, so the sender arrives in the same shape as on the classic inbox, plus two fields specific to this inbox.

Field	Description
`sender.name`	Full name
`sender.profile_url`	Public profile URL — match it against your own records
`sender.member_urn`	`urn:li:member:<id>`, stable across LinkedIn
`sender.degree`	Connection degree, `1`, `2` or `3`
`sender.urn_raw`	The Sales Navigator id. Pass it as `recipient_urn` to reply.

Resolution costs one lookup per contact, not per message, and is cached: the first message from someone takes about half a second longer, their next ones are instant. No credit is charged. If the lookup fails, the event is still delivered with sender.urn_raw alone.

metadata.conversation_urn is a fs_salesMessagingThread URN, not a classic msg_conversation one. Pass its thread id to List Inbox or Get Conversation with sales_nav: true to read the thread, and reply with Send Message using inmail: true.

Accepted Invitation

Triggered when one or more connection requests you sent are accepted. Detected by a background worker that polls the connections list every ~6 hours and diffs against the previously stored snapshot. The payload batches all new connections detected in the same check.

{
  "account_id": "69ee261e41fc4cbecf9f34c9",
  "account_name": "[email protected]",
  "platform": "linkedin",
  "event": {
    "type": "accepted_invitation",
    "new_connections": [
      {
        "profile_url": "https://www.linkedin.com/in/maruthigudi/",
        "name": "Maruthi Gudi",
        "job_title": "Building High-Performance Tech & FinTech Teams | Headhunter @ HackerTrail",
        "profile_picture": "https://media.licdn.com/dms/image/v2/D4E03AQEEUE9iAq2LXA/profile-displayphoto-shrink_100_100/B4EZYY8bulGYAU-/0/1744175218426"
      },
      {
        "profile_url": "https://www.linkedin.com/in/musokeshaibu/",
        "name": "Musoke Shaibu",
        "job_title": "Building the definitive operating system for sales, marketing, and research.",
        "profile_picture": "https://media.licdn.com/dms/image/v2/D4D03AQGCOZ3SrVT5Tg/profile-displayphoto-shrink_200_200/B4DZZtP29UGcAY-/0/1745589597790"
      }
    ],
    "count": 2,
    "timestamp": "2026-04-27T14:52:59.970134"
  },
  "timestamp": "2026-04-27T14:52:59.970144"
}

Field reference

Field	Type	Description
`event.new_connections`	`array`	Profiles that accepted your connection request since the last check
`event.new_connections[].profile_url`	`string`	Public profile URL of the connection
`event.new_connections[].name`	`string`	Display name
`event.new_connections[].job_title`	`string \| null`	Headline / current role as shown on the platform
`event.new_connections[].profile_picture`	`string \| null`	CDN URL of the profile picture (may expire)
`event.count`	`integer`	Length of `new_connections`

When you create a webhook subscribed to accepted_invitation (or all), the API performs an initial sync of your existing connections in the background. The first detection check then runs ~6 hours later and every 6 hours thereafter.

Invitation Received

Triggered when the account receives one or more new connection requests. Detected by the same background worker as accepted_invitation (~6 hour polling cadence by default), so it’s suited for inbound automation — auto-accepting, routing to a CRM, or replying — rather than instant notifications. The payload batches all new invitations detected in the same check.

{
  "account_id": "69ee261e41fc4cbecf9f34c9",
  "account_name": "[email protected]",
  "platform": "linkedin",
  "event": {
    "type": "invitation_received",
    "new_invitations": [
      {
        "name": "Jane Cooper",
        "profile_url": "https://www.linkedin.com/in/jane-cooper",
        "profile_picture": "https://media.licdn.com/dms/image/v2/D4D03AQFcP6361wcRgg/profile-displayphoto-scale_200_200",
        "subtitle": "Growth Marketing Lead @ Acme",
        "message": "Hi! I'd love to connect and exchange about your product.",
        "sent_time": "2 days ago",
        "invitation_id": "7498280075365183488",
        "shared_secret": "aBcDeFgH",
        "entity_urn": "urn:li:fsd_invitation:7498280075365183488"
      }
    ],
    "count": 1,
    "timestamp": "2026-08-29T15:58:43.629574"
  },
  "timestamp": "2026-08-29T15:58:43.629583"
}

Field reference

Field	Type	Description
`event.new_invitations`	`array`	Connection requests received since the last check
`event.new_invitations[].name`	`string`	Display name of the sender
`event.new_invitations[].profile_url`	`string`	Profile URL of the sender
`event.new_invitations[].profile_picture`	`string \| null`	CDN URL of the profile picture (may expire)
`event.new_invitations[].subtitle`	`string \| null`	Headline of the sender
`event.new_invitations[].message`	`string \| null`	The note attached to the invitation, if any
`event.new_invitations[].sent_time`	`string`	Relative time the invitation was sent (e.g. `"2 days ago"`)
`event.new_invitations[].invitation_id`	`string`	Invitation ID as a string
`event.new_invitations[].shared_secret`	`string \| null`	Secret required to accept the invitation
`event.new_invitations[].entity_urn`	`string`	Invitation URN — pass it with `shared_secret` to Accept Invitation
`event.count`	`integer`	Length of `new_invitations`

When you create a webhook subscribed to invitation_received (or all), the API stores a baseline of your currently pending invitations in the background — the existing backlog is never notified, only invitations received after the webhook was created.

To auto-accept an incoming invitation, call Accept Invitation with the payload’s entity_urn and shared_secret. invitation_id is delivered as a string because the raw 19-digit number exceeds JavaScript’s Number.MAX_SAFE_INTEGER — keep it as a string end to end.

Disconnection

Triggered when the account’s platform session expires, the cookie is invalidated, or the user logs out. Sent to every webhook attached to the account regardless of subscription filters.

{
  "account_id": "69ee261e41fc4cbecf9f34c9",
  "account_name": "[email protected]",
  "platform": "linkedin",
  "event": {
    "type": "disconnection",
    "reason": "LinkedIn cookie invalid or expired",
    "timestamp": "2026-04-28T09:15:30.123456"
  },
  "timestamp": "2026-04-28T09:15:30.123456"
}

Field reference

Field	Type	Description
`event.reason`	`string`	Human-readable cause (e.g. `"Token expired (detected after 10 reconnections)"`, `"LinkedIn cookie invalid or expired"`)

When you receive a disconnection event, monitoring stops automatically and every webhook attached to the account is paused (with auto_paused: true). You need to re-authenticate the account via POST /v2/login (or POST /v2/checkpoint if a 2FA is required) — paused webhooks are auto-restarted on a successful re-login.

Architecture

Unlike the V1 webhook system which required creating a separate “webhook account”, the V2 system works with your existing accounts:

V2 accounts are created via POST /v2/login (profiles, messages, network, etc.)
Webhooks are configurations that attach to those accounts
One account can have multiple webhooks with different event filters
Starting/stopping monitoring is done per webhook

Getting Started

Accounts

Profiles

Messaging

Network

Content

Recruiting

Credits

Logs

Email Enrichment

Webhooks (Real-Time)

Webhooks Introduction

Delivery Modes

Hosted Mode

Custom Mode

Delivery & retries (custom mode)

How It Works

Event Types

Event Payload Format

Message Received

Email events

Sales Navigator inbox

Accepted Invitation

Invitation Received

Disconnection

Architecture

​Delivery Modes

Hosted Mode

Custom Mode

​Delivery & retries (custom mode)

​How It Works

​Event Types

​Event Payload Format

​Message Received

​Email events

​Sales Navigator inbox

​Accepted Invitation

​Invitation Received

​Disconnection

​Architecture

Delivery Modes

Delivery & retries (custom mode)

How It Works

Event Types

Event Payload Format

Message Received

Email events

Sales Navigator inbox

Accepted Invitation

Invitation Received

Disconnection

Architecture