Quick reference

The Availability column marks how an event is delivered. Events with no marker are delivered in real time. See Delivery availability below for the full meaning of each marker.

Delivery availability

GET /v1/webhooks/events returns the live catalogue, with an availability field on the events that are not delivered in real time. Three values are possible:

Default and opt-in events

When you create a webhook without an events array, it subscribes to that source's default set. Any event listed for the source can also be subscribed explicitly.

Payload structure

Every delivery shares the same outer envelope:

{
  "id":           "wdl_YOUR_DELIVERY_ID",
  "webhook_id":   "wh_YOUR_WEBHOOK_ID",
  "event":        "message.received",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "event":       "message.received",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "message_id":  "msg_YOUR_MESSAGE_ID",
    "text":        "Hello, how can I help?",
    "sender": {
      "name":        "Alex Jordan",
      "profile_url": "https://www.linkedin.com/in/alexjordan",
      "provider_id": "urn:li:member:123456789"
    },
    "attachments": [],
    "occurred_at": "2026-05-28T09:15:00.000Z"
  },
  "delivered_at": "2026-05-28T09:15:01.234Z"
}

id is the delivery ID (wdl_...); webhook_id (wh_...) references the webhook.

Three fields are guaranteed inside data on every delivery, whatever the source: account_id, event (the canonical event name, identical to the top-level event), and occurred_at. Together they are the recommended deduplication key, because the top-level id changes on every retry.

Messaging events

Messaging events notify your endpoint whenever a message or chat changes state on a connected account. The message.* payloads include the full message content; the chat.* events describe a chat thread rather than a single message.

message.received

Fired when an inbound message arrives in any chat, classic LinkedIn messages or InMail. Fires for inbound messages only; a message the account sent does not fire it (use message.delivered for outbound confirmation).

message.delivered

Fired when an outbound message was delivered. Use it to close the send loop in fire-and-forget agent patterns.

message.read

Fired when a message in a chat was read by the recipient. The payload may include reader identity where available.

message.reaction

Fired when a reaction is added to a message. The data object includes a reaction field with the reaction value.

message.edited

Fired when a message is edited after send. The text field carries the post-edit content.

message.deleted

Fired when a message is deleted. The text field may be absent.

chat.updated

Fired when a chat's container state changed, for example archived, muted, or read-state. Useful for inbox automation. chat.updated is opt-in, name it in events[] to receive it. See the Messaging events article for the delivered data shape.

chat.deleted

Fired when a chat thread was deleted. chat.deleted is opt-in, name it in events[] to receive it.

User events

connection.accepted

Fired when a pending invitation you sent was accepted by the recipient. Once received, the two members are connected and messaging is available without InMail credits.

connection.new

Fired when any new relation appears on the account, not just ones you invited, so it is a superset of connection.accepted. connection.new is opt-in, name it in events[] to receive it.

Account status events

Account events track the lifecycle of connected LinkedIn accounts, from creation through session expiry and eventual removal.

account.created

Fired when a new account link completes successfully for the first time, the initial connect path.

account.connected

Fired when the account is in a healthy, connected state. That covers a health check confirming the account is fine, and a connect that turns out to reactivate an account you had previously disconnected ("recovered": true) and finds it healthy.

A reactivating connect always reports the state the account actually comes back in, so if the reconnection is not clean you get the event for that state instead, one of account.reconnect_needed, account.restricted, or account.disconnected. The event name and data.status in the same delivery never disagree.

account.synced · no_longer_realtime

Historically fired when a synchronization cycle completed. No longer delivered on the current platform, and there is no equivalent event or read-path, do not build on it.

account.reconnected

Fired when an existing account was re-authorized in place, credentials refreshed without creating a new account ID.

Reactivating an account you had previously disconnected does not fire this event. That connect reports the state the account comes back in, so subscribe to account.connected (and the degraded states) if you want to hear about reactivations.

account.reconnect_needed

Fired when credentials expire or the session cookie is invalidated. The account remains in your workspace but is inactive until re-authentication. Trigger a reconnect flow from the dashboard or call POST /v1/auth/intent with the account's account_id in the body to re-authenticate it in place.

account.restricted · not_realtime

Fired when LinkedIn restricted the account. Actions on it will fail until the restriction is lifted, so treat this as a stop signal: pause outreach for the account and surface it for a human. A daily account reconciliation normally notices the restriction (allow up to 24 hours for that path), but a connect that observes the account already restricted can also deliver this event immediately. Read the account directly with GET /v1/accounts/{account_id} if you need the state sooner than either.

account.creation_failed · no_longer_realtime

The initial account-link attempt failed before completion (terminal, no account was established). No longer delivered, detect via an on-demand account read (GET /v1/accounts/{account_id}).

account.disconnected

Fired when the account is in the disconnected state and cannot act until it is reconnected. Causes include an explicit disconnect or deletion, and a connect or reconnect attempt that observes an already-disconnected account without removing it. Where the account was actually removed, its account ID will subsequently 404 and any webhooks scoped to it stop delivering; where it was not, read the account back to confirm.

account.error

Fired when account synchronization encountered an error (needs investigation, not a credentials issue).

account.paused

Fired when account synchronization was stopped or paused externally, not an error, and it may resume automatically.

account.connecting · no_longer_realtime

Historically a transient, high-frequency event fired while an account link was in progress. No longer delivered on the current platform. Detect link-in-progress via the account read (GET /v1/accounts/{account_id}) instead.

account.permission_revoked · no_longer_realtime

A LinkedIn-side scope or permission the account relies on was withdrawn. No longer delivered, detect via an on-demand account read (GET /v1/accounts/{account_id}).

account.initial_sync.running · account.initial_sync.completed · account.initial_sync.failed

The initial history backfill for a newly connected account is bracketed by these three opt-in events: exactly one account.initial_sync.running (informational), followed by exactly one of account.initial_sync.completed (the actionable signal, full LinkedIn history is now queryable) or account.initial_sync.failed. The failed delivery carries a neutral reason, one of internal, proxy, or provider. See the Account status events article for the full treatment.

Errors you may hit

Full envelope shapes are in the error reference.

Next steps

• Messaging events: full payloads for the 8 messaging events.
• User events: full payloads for the 2 connection events.
• Account status events: full payloads for all 15 account-status events.
• Verifying signatures: validate every delivery before you process it.