Linked APILinked API

Webhook Events

Receive workflow, account, and LinkedIn activity events in real time. Instead of polling for a workflow result, register a webhook once and Linked API delivers an event to your endpoint whenever a workflow changes state, a LinkedIn account changes status, a message is observed in a monitored inbox, or a connection changes in a monitored network.

How it works

  • You register a single endpoint URL that receives events. A client may hold one active webhook at a time.
  • Every event is delivered as an HTTP POST with a JSON body (the event envelope below).
  • Respond with any 2xx status to acknowledge. A non-2xx response, or a timeout, is retried with exponential backoff for up to 8 attempts before the delivery is marked failed.

Register and manage your webhook through the Admin API.

Event envelope

Every delivery has the same shape:

json
{
  "id": "workflow.completed:wf-64835e7c-...",
  "type": "workflow.completed",
  "createdAt": "2026-06-25T12:00:00.000Z",
  "data": {
    "workflowId": "wf-64835e7c-...",
    "accountId": "f9b4346a-...",
    "status": "completed",
    "result": { }
  }
}
  • id – stable, unique event identifier. Use it to deduplicate: a retried delivery reuses the same id.
  • type – event type, one of the values listed below.
  • createdAt – ISO 8601 timestamp of when the event was produced.
  • data – event-specific payload, described per event type below.

Delivery order is best-effort and not guaranteed. Correlate events by type, data.status, and createdAt rather than by arrival order.

Workflow events

data carries workflowId, accountId, and status. All events for one run share the same workflowId, so you can correlate them.

  • workflow.created – your request was accepted and queued. status is pending.
  • workflow.started – the workflow actually started running. status is running.
  • workflow.completed – the workflow reached a terminal state. status is completed or failed.

data.result is included only on workflow.completed, and only in fat payload mode. Cancelled workflows do not emit a webhook.

Account events

data carries accountId and status, emitted when a connected LinkedIn account changes status.

  • account.reconnectionRequired – the account needs the user to reconnect. status is reconnection_required.
  • account.active – the account (re)connected and is operational. status is active.
  • account.frozen – the account was frozen, for example due to an unpaid subscription. status is frozen.
  • account.deleted – the account was deleted. status is deleted.

Inbox events

The inbox.* namespace covers messages observed in a connected account's inbox, as opposed to the state of your own Linked API entities. These events fire for accounts that have inbox monitoring enabled via st.syncInbox / nv.syncInbox, one event per inbox message.

  • inbox.messageReceived – an incoming message was observed in the inbox.
  • inbox.messageSent – an outgoing message from the account was observed. This covers messages sent through the LinkedIn UI and messages sent through the Linked API, so an API-sent message emits inbox.messageSent in addition to its workflow.completed.

data carries the message with the following fields:

  • accountId – the connected LinkedIn account the message belongs to.
  • type – inbox type the message belongs to (st or nv).
  • threadId – identifier of the conversation thread. Pass it to st.sendMessage / nv.sendMessage to reply.
  • personUrl – LinkedIn URL of the other participant.
  • messageId – unique identifier of the message, matching the id returned by inbox polling.
  • sender – us for inbox.messageSent, them for inbox.messageReceived.
  • text – message text.
  • time – ISO 8601 timestamp of the message.

Because inbox.messageSent also fires for outbound messages your own automations send, filter by data.sender and data.type rather than assuming every event is a fresh inbound reply.

Network events

The network.* namespace covers changes to a connected account's connection graph. These events fire for accounts that have network monitoring enabled via st.syncNetwork, one event per connection change.

  • network.connectionRequestReceived – someone sent the account a connection request. A new incoming pending invitation was observed.
  • network.connectionAccepted – a new connection that matches a request the account sent. The other person accepted an outgoing invitation.
  • network.connectionAdded – a new connection that is not attributable to a request the account sent, for example an incoming request the account accepted, or a connection formed outside the API.

data carries the connection event with the following fields:

  • accountId – the connected LinkedIn account the event belongs to.
  • personUrl – LinkedIn URL of the other person.
  • detectedAt – ISO 8601 timestamp of when Linked API observed the event, matching the detectedAt returned by network polling.

Payload modes

The payload mode controls how much data workflow.completed carries:

  • fat (default) – the full workflow result is inlined in data.result.
  • thin – data.result is omitted; fetch the result via the workflow API using data.workflowId.

You can switch the mode at any time when managing the webhook.

Receiving events

Your endpoint should:

  1. Read the JSON body and branch on type.
  2. Respond 2xx quickly to acknowledge. Do heavy work asynchronously – a slow endpoint will time out and be retried.
  3. Deduplicate on the envelope id. Deliveries are at-least-once, so the same event can arrive more than once.
PreviousActions OverviewNextSending Message