Working with Webhooks

Receive workflow and account 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 or a LinkedIn account changes status.

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:

{
  "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.

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.