# Webhooks Overview

Receive workflow, account, inbox and network events in real time: register one endpoint and Linked API delivers every event to it – no polling required.

> The API Reference is also the SDK and CLI reference. Consecutive code fences marked `tab=HTTP`, `tab=Node`, `tab=Python` and `tab=CLI` are the same call on each surface (a fence marked `tab=HTTP,CLI` is the same text for both), and a block between `:::surface <names>` and `:::` applies only to the surfaces it names. Identifiers in the text are written as in Node and in HTTP JSON (camelCase); the Python SDK spells methods, parameters and result attributes in snake_case (`sendMessage` → `send_message`, `reconnectionLink` → `reconnection_link`), while names inside HTTP JSON stay camelCase.

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. The webhook also receives an event whenever a [signal](/docs/signals-overview) detects something new.

:::surface node
In the Node SDK, `verifyWebhookSignature()` checks a delivery and `parseWebhookEvent()` turns it into a typed event – see [Receiving events](#receiving-events). The webhook itself is managed with `admin.webhooks` – see [Managing webhooks](/docs/admin-webhooks).
:::

:::surface python
In the Python SDK, `verify_webhook_signature()` checks a delivery and `parse_webhook_event()` turns it into a typed event – see [Receiving events](#receiving-events). The webhook itself is managed with `admin.webhooks` – see [Managing webhooks](/docs/admin-webhooks).
:::

:::surface cli
In the CLI you register and manage the webhook with `linkedin admin webhook` commands – see [Managing webhooks](/docs/admin-webhooks?surface=cli). Receiving deliveries is the job of your own endpoint.
:::

## How it works

- You register a single endpoint URL that receives events. A client may hold one active webhook at a time.
- Every event your webhook receives is delivered as an HTTP `POST` with a JSON body (the event envelope below). By default that is every event; you can [choose which events](/docs/webhook-event-types#event-selection) it receives.
- 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.
- Two optional settings secure the delivery: [custom headers](/docs/webhook-custom-headers), so an endpoint that requires authentication lets us in, and a [signature](/docs/webhook-signature-verification), so you can prove a delivery came from Linked API. Both are off by default and neither changes anything until you turn it on.

Set this up either way: in the [platform dashboard](https://app.linkedapi.io/webhook), or programmatically through the [Admin API](/docs/admin-webhooks). Both reach the same webhook, so you can register it in the dashboard and change it from code, or the other way round.

:::surface node,python
In the SDKs, the Admin API's webhook endpoints are the methods of `admin.webhooks` on the [admin client](/docs/admin-overview#authentication). Each call is shown on [Managing Webhooks](/docs/admin-webhooks).
:::

:::surface cli
In the CLI, they are the `linkedin admin webhook` commands. Each command is shown on [Managing Webhooks](/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 [event types](/docs/webhook-event-types).
- `createdAt` – ISO 8601 timestamp of when the event was produced.
- `data` – event-specific payload, described per event type on [Event Types](/docs/webhook-event-types).

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

## 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. If signing is on, [verify the signature](/docs/webhook-signature-verification) against the **raw** body, before parsing it.
2. Read the JSON body and branch on `type`.
3. Respond `2xx` quickly to acknowledge. Do heavy work asynchronously – a slow endpoint will time out and be retried.
4. Deduplicate on the envelope `id`. Deliveries are at-least-once, so the same event can arrive more than once.

:::surface node
The Node SDK ships helpers for the first two steps: `verifyWebhookSignature` checks the [signature](/docs/webhook-signature-verification#verifying-a-delivery), and `parseWebhookEvent` turns the body into a typed event, so branching on `type` narrows `data`. Both take the raw body, so read it unparsed – in Express, with `express.raw()`:
:::

:::surface python
The Python SDK ships helpers for the first two steps: `verify_webhook_signature` checks the [signature](/docs/webhook-signature-verification#verifying-a-delivery), and `parse_webhook_event` turns the body into a typed event – branch on its class with `isinstance` to reach typed `data`. Both take the raw body, so read it unparsed – in FastAPI, with `await request.body()`:
:::

:::surface http
Without an SDK the endpoint is a few lines in any language. Here it is in Node.js with Express, reading the body unparsed with `express.raw()` and checking it with the reference `verifyWebhookSignature` from [Signature Verification](/docs/webhook-signature-verification#verifying-a-delivery):
:::

:::surface cli
The CLI configures webhooks but does not receive them: your endpoint is a small server in any language. Here it is in Node.js with Express, reading the body unparsed with `express.raw()` and checking it with the reference `verifyWebhookSignature` from [Signature Verification](/docs/webhook-signature-verification#verifying-a-delivery):
:::

```js tab=HTTP,CLI
const express = require("express")
// The reference implementation from Signature Verification, saved next to this file as verify-webhook-signature.js.
const { verifyWebhookSignature } = require("./verify-webhook-signature")

const app = express()
app.use(express.raw({ type: "application/json" }))

app.post("/hooks/linkedapi", (req, res) => {
  // Skip this check if signing is off for your webhook.
  const isAuthentic = verifyWebhookSignature({
    rawBody: req.body,
    timestamp: req.headers["linked-api-signature-timestamp"],
    signature: req.headers["linked-api-signature"],
    secret: process.env.LINKED_API_WEBHOOK_SECRET,
    nowSeconds: Math.floor(Date.now() / 1000),
  })
  if (!isAuthentic) {
    res.sendStatus(401)
    return
  }

  const event = JSON.parse(req.body.toString("utf8"))

  switch (event.type) {
    case "workflow.completed":
      console.log(`Workflow ${event.data.workflowId} finished: ${event.data.status}`)
      console.log("Result:", event.data.result) // present in fat mode only
      break
    case "account.reconnectionRequired":
      console.log(`Account ${event.data.accountId} needs reconnection.`)
      break
    case "inbox.messageReceived":
      // personHashedUrl is set except on Recruiter Lite (rc) messages; personPublicUrl is null until the person is resolved.
      console.log(`New message from ${event.data.personPublicUrl ?? event.data.personHashedUrl}: ${event.data.text}`)
      break
    case "inbox.messageSent":
      console.log(`Outgoing message in thread ${event.data.threadId}`)
      break
    case "network.connectionAccepted":
      console.log(`${event.data.personUrl} accepted your connection request`)
      break
    case "network.connectionRequestReceived":
      console.log(`New connection request from ${event.data.personUrl}`)
      break
    case "webhook.test":
      console.log("Test event:", event.data.message)
      break
  }

  // Acknowledge fast. A non-2xx response makes Linked API retry with backoff.
  res.sendStatus(200)
})
```

```typescript tab=Node
import express from "express";
import {
  parseWebhookEvent,
  verifyWebhookSignature,
  WEBHOOK_SIGNATURE_HEADER,
  WEBHOOK_SIGNATURE_TIMESTAMP_HEADER,
} from "@linkedapi/node";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/hooks/linkedapi", (req, res) => {
  // Skip this check if signing is off for your webhook.
  const isAuthentic = verifyWebhookSignature({
    rawBody: req.body as Buffer,
    timestamp: req.headers[WEBHOOK_SIGNATURE_TIMESTAMP_HEADER],
    signature: req.headers[WEBHOOK_SIGNATURE_HEADER],
    secret: process.env.LINKED_API_WEBHOOK_SECRET,
  });
  if (!isAuthentic) {
    res.sendStatus(401);
    return;
  }

  const event = parseWebhookEvent(req.body as Buffer);

  switch (event.type) {
    case "workflow.completed":
      console.log(`Workflow ${event.data.workflowId} finished: ${event.data.status}`);
      console.log("Result:", event.data.result); // present in fat mode only
      break;
    case "account.reconnectionRequired":
      console.log(`Account ${event.data.accountId} needs reconnection.`);
      break;
    case "inbox.messageReceived":
      // personHashedUrl is set except on Recruiter Lite (rc) messages; personPublicUrl is null until the person is resolved.
      console.log(`New message from ${event.data.personPublicUrl ?? event.data.personHashedUrl}: ${event.data.text}`);
      break;
    case "inbox.messageSent":
      console.log(`Outgoing message in thread ${event.data.threadId}`);
      break;
    case "network.connectionAccepted":
      console.log(`${event.data.personUrl} accepted your connection request`);
      break;
    case "network.connectionRequestReceived":
      console.log(`New connection request from ${event.data.personUrl}`);
      break;
    case "webhook.test":
      console.log("Test event:", event.data.message);
      break;
  }

  // Acknowledge fast. A non-2xx response makes Linked API retry with backoff.
  res.sendStatus(200);
});
```

```python tab=Python
import os

from fastapi import FastAPI, Request, Response
from linkedapi import (
    WEBHOOK_SIGNATURE_HEADER,
    WEBHOOK_SIGNATURE_TIMESTAMP_HEADER,
    AccountWebhookEvent,
    MessageWebhookEvent,
    NetworkWebhookEvent,
    UnknownWebhookEvent,
    WebhookTestEvent,
    WorkflowWebhookEvent,
    parse_webhook_event,
    verify_webhook_signature,
)

app = FastAPI()


@app.post("/hooks/linkedapi")
async def receive(request: Request) -> Response:
    raw_body = await request.body()

    # Skip this check if signing is off for your webhook.
    is_authentic = verify_webhook_signature(
        raw_body=raw_body,
        timestamp=request.headers.get(WEBHOOK_SIGNATURE_TIMESTAMP_HEADER),
        signature=request.headers.get(WEBHOOK_SIGNATURE_HEADER),
        secret=os.environ.get("LINKED_API_WEBHOOK_SECRET"),
    )
    if not is_authentic:
        return Response(status_code=401)

    event = parse_webhook_event(raw_body)

    if isinstance(event, WorkflowWebhookEvent):
        if event.type == "workflow.completed":
            print(f"Workflow {event.data.workflow_id} finished: {event.data.status}")
            print("Result:", event.data.result)  # present in fat mode only
    elif isinstance(event, AccountWebhookEvent):
        if event.type == "account.reconnectionRequired":
            print(f"Account {event.data.account_id} needs reconnection.")
    elif isinstance(event, MessageWebhookEvent):
        if event.type == "inbox.messageReceived":
            # person_hashed_url is set except on Recruiter Lite (rc) messages; person_public_url is None until the person is resolved.
            person = event.data.person_public_url or event.data.person_hashed_url
            print(f"New message from {person}: {event.data.text}")
        elif event.type == "inbox.messageSent":
            print(f"Outgoing message in thread {event.data.thread_id}")
    elif isinstance(event, NetworkWebhookEvent):
        if event.type == "network.connectionAccepted":
            print(f"{event.data.person_url} accepted your connection request")
        elif event.type == "network.connectionRequestReceived":
            print(f"New connection request from {event.data.person_url}")
    elif isinstance(event, WebhookTestEvent):
        print("Test event:", event.data.message)
    elif isinstance(event, UnknownWebhookEvent):
        # A type this SDK version doesn't know yet. Acknowledge it so it isn't retried.
        print(f"Ignoring event type {event.type}")

    # Acknowledge fast. A non-2xx response makes Linked API retry with backoff.
    return Response(status_code=200)
```

:::surface node
`parseWebhookEvent` throws an `Error` when the body is not valid JSON or lacks the envelope `id` or `type`. It checks only that `type` is a string, so an event type added after your SDK version reaches your code as it is. It returns `TWebhookEvent`, a union of one type per area – see [Event Types](/docs/webhook-event-types).
:::

:::surface python
`parse_webhook_event` raises `ValueError` when the body is not valid JSON or lacks the envelope `id` or `type`. Since `linkedapi` 1.4.7, an event type the installed version doesn't know yet no longer raises: it is returned as `UnknownWebhookEvent`, with its payload as a plain dict in `data`. It returns `WebhookEvent`, a union of one model per area plus `UnknownWebhookEvent`, with snake_case `data` fields – see [Event Types](/docs/webhook-event-types). Every event's `type` is an open string, so branch with `isinstance` on the event classes, as above, rather than on `type` alone.
:::
