# Webhook Events

Receive workflow, account, inbox, and network events in real time. Register one endpoint and Linked API delivers an event 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 – no polling required.

Receive workflow, account, and LinkedIn activity events in real time. Instead of [polling for a workflow result](/docs/executing-workflows), 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](/docs/admin-webhooks).

## 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](/docs/monitoring-inbox) 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`](/docs/action-st-send-message) / [`nv.sendMessage`](/docs/action-nv-send-message) to reply.
- `personUrl` – LinkedIn URL of the other participant.
- `messageId` – unique identifier of the message, matching the `id` returned by [inbox polling](/docs/monitoring-inbox).
- `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](/docs/monitoring-network) 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](/docs/monitoring-network).

## 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](/docs/executing-workflows) using `data.workflowId`.

You can switch the mode at any time when [managing the webhook](/docs/admin-webhooks).

## 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.