Webhooks

Direct sends Unipile's webhooks for three sources: messaging (message_received), users (new_relation) and account_status. You register them through the API (Unipile also lets you add them in its dashboard; Direct has only the API). A webhook belongs to the workspace of the key that created it: a key lists and deletes its own workspace's webhooks only, and only that workspace's accounts send to them.

Register A Webhook#

curl -sS -X POST "https://direct.lempile.com/api/v1/webhooks" \
  -H "X-API-KEY: $DIRECT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_url": "https://app.example.com/hooks/linkedin-messages",
    "source": "messaging",
    "name": "messages",
    "headers": [{ "key": "x-webhook-secret", "value": "your-own-secret" }]
  }'

{ "object": "WebhookCreated", "webhook_id": "a1B2c3D4e5F6g7H8i9J0kL" }

GET /api/v1/webhooks lists your workspace's (header values as ********), DELETE /api/v1/webhooks/{hook_id} deletes one (hook_id is the webhook_id it was created with) (its deliveries still waiting are dropped). There is no update: delete and create again.

Events#

The "accepted, never sent" events are taken at registration so a Unipile setup registers unchanged, but Direct never sends them: LinkedIn has no delivery receipt of its own, and the others aren't states a Lempile account goes through. message_read, message_reaction, message_edited and message_deleted come only from the live stream (see Timing).

Authenticating Deliveries#

Direct doesn't sign payloads. Every delivery carries the headers you gave the webhook, exactly; put a secret there and check it on every request, comparing in constant time. That's how Unipile setups usually authenticate (for example a static x-unipile-signature header).

Each delivery also has user-agent: Lempile-Direct-Webhooks/1 and content-type: application/json (or the form type).

Payloads#

messaging: message_received#

A new message in one of the account's chats: received, or sent by the account from anywhere (Direct, LinkedIn's website or apps), as Unipile does.

{
  "account_id": "00000000-0000-4000-8000-0000000000a1",
  "account_type": "LINKEDIN",
  "account_info": { "type": "LINKEDIN", "feature": "classic", "user_id": "ACoAAAbcdefghijklmnop" },
  "event": "message_received",
  "chat_id": "2-QUFBQXRocmVhZPv_b25lMQ",
  "timestamp": "2026-10-29T09:41:07.000Z",
  "webhook_name": "messages",
  "message_id": "2-_vptc2cwMTMyIQ",
  "message": "Sounds good",
  "sender": {
    "attendee_id": "ACoAAAzyxwvutsrqponml",
    "attendee_name": "Bob Buyer",
    "attendee_provider_id": "ACoAAAzyxwvutsrqponml",
    "attendee_profile_url": "https://www.linkedin.com/in/ACoAAAzyxwvutsrqponml",
    "attendee_public_identifier": null,
    "attendee_specifics": {
      "provider": "LINKEDIN",
      "member_urn": "urn:li:member:123456789",
      "network_distance": "DISTANCE_1",
      "occupation": "Head of Sales at Example",
      "is_company": false
    }
  },
  "attendees": [
    {
      "attendee_id": "ACoAAAzyxwvutsrqponml",
      "attendee_name": "Bob Buyer",
      "attendee_provider_id": "ACoAAAzyxwvutsrqponml",
      "attendee_profile_url": "https://www.linkedin.com/in/ACoAAAzyxwvutsrqponml",
      "attendee_public_identifier": null,
      "attendee_specifics": {
        "provider": "LINKEDIN",
        "member_urn": "urn:li:member:123456789",
        "network_distance": "DISTANCE_1",
        "occupation": "Head of Sales at Example",
        "is_company": false
      }
    }
  ],
  "attachments": [],
  "is_sender": false,
  "subject": null,
  "provider_chat_id": "2-QUFBQXRocmVhZPv_b25lMQ",
  "provider_message_id": "2-_vptc2cwMTMyIQ",
  "is_event": 0,
  "chat_pinned": 0,
  "quoted": null,
  "reply_to": null,
  "is_forwarded": null,
  "is_view_once": null,
  "chat_content_type": null,
  "message_type": "MESSAGE",
  "is_group": false,
  "folder": ["INBOX", "INBOX_LINKEDIN_CLASSIC"],
  "event_type": null
}

Every key and every type is as in Unipile's own deliveries (checked against real ones). The ids are LinkedIn's (see below), as every Direct route answers them.

A person (sender, each of attendees, read_by, reaction_sender):

messaging: message_read, message_reaction, message_edited, message_deleted#

The same payload as message_received, about the message concerned, with its own event:

Each is sent once (a receipt once per message and reader, a reaction once per message, emoji and person).

users: new_relation#

A new connection: an invitation accepted, either way.

{
  "event": "new_relation",
  "account_id": "00000000-0000-4000-8000-0000000000a1",
  "account_type": "LINKEDIN",
  "webhook_name": "relations",
  "user_full_name": "Bob Buyer",
  "user_provider_id": "ACoAAAzyxwvutsrqponml",
  "user_public_identifier": "bob-buyer",
  "user_profile_url": "https://www.linkedin.com/in/bob-buyer/",
  "user_picture_url": "https://media.licdn.com/dms/image/x/400.jpg",
  "timestamp": 1793260931000
}

timestamp is when the connection was made, in milliseconds since 1970 (a number, to the second), as Unipile's. user_picture_url may be null.

account_status#

{
  "AccountStatus": {
    "account_id": "00000000-0000-4000-8000-0000000000a1",
    "account_type": "LINKEDIN",
    "message": "CREDENTIALS"
  }
}

The event names you filter on are the lowercase forms (credentials, creation_success…). A SYNC_SUCCESS also has "Product": "classic" beside AccountStatus, as every one of Unipile's does.

Hosted auth notify_url#

Not a registered webhook: a hosted auth link's notify_url gets exactly {"status": "CREATION_SUCCESS" | "RECONNECTED", "account_id", "account_type": "LINKEDIN", "name"} when the account works, delivered and retried like a webhook, with no extra header.

Delivery#

• A POST, 30 seconds at most per try.
• Any 2xx is delivered and never sent again.
• A 5xx, 408, 425, 429, a timeout or a refused connection is tried again 30 seconds, 2 minutes, 10 minutes, 30 minutes and 2 hours later (5 more tries). Any other answer (a 4xx, a redirect) is final.
• Deliveries waiting for a retry are kept encrypted on Direct's disk: a restart of Direct sends them.
• Each delivery is independent: a slow receiver holds no other.
• A delivery that timed out on Direct's side may still have reached you, so you can receive one twice. Make your handler idempotent on message_id (or user_provider_id, or the status and account).

Timing#

Messages arrive in real time, day and night. For each account some messaging or users webhook wants, Direct keeps LinkedIn's own live connection open (the one LinkedIn's messaging page keeps open), through the account's own session and proxy. A new message (received, or sent by the account from anywhere), a read receipt, a reaction, an edit or a deletion reaches your webhook within seconds of LinkedIn telling the account's browser.

Behind it, Direct still reads each account's inbox and relations, through the account's own session and pacing, and only for what some webhook wants (no webhook, no read). It catches anything the live connection missed:

• New connections: LinkedIn's live connection never names a new connection, but someone accepting an invitation is a notification. When it signals an invitation, the notifications or My Network badge going up, or an in-app alert, Direct reads the newest relations within seconds (one call; at most once every 90 seconds and 96 times a day an account): the new connection then reaches your users webhook within about a minute. Otherwise the regular read finds it. Unipile's own new_relation comes by polling, up to 8 hours after.
• Every message is sent once, whichever path saw it first.
• When the live connection drops, it reconnects within seconds, and the inbox is read within a minute after any gap of 30 seconds or more, as LinkedIn's own page re-syncs: messages from the gap arrive then, a minute or two late. While the connection stays down, the inbox is read every 2 to 5 minutes again.
• A conversation whose last activity moved has its latest messages read: up to 8 conversations a read (the others next read), up to 20 new messages each, oldest first.
• Status changes go out as soon as any call (yours, or a read) sees them.
• The timezone is the account's own (America/New_York unless Lempile set another).
• The first read for an account only remembers where things are: it sends nothing already there. An account whose reading was stopped for more than 6 hours starts again the same way, so messages from that gap aren't sent; read them with GET /chats and GET /chats/{chat_id}/messages.
• The reads cost the account about 190 LinkedIn calls on a quiet day while the live connection is up (about 300 without it): one per read, one per conversation with new activity, one per (re)connection (LinkedIn closes its live connection every 12 to 14 minutes, as it does for its own page: about 100 a day), and for a message the live connection didn't fully describe, one or two to read it. They stop for the day at 450, and pause while the account has used 80% of its daily calls, so your own calls keep most of the budget.
• A signed-out account (CREDENTIALS) isn't read until it's OK again; a rest after LinkedIn's "too many" is waited out.