Monitoring & Recovering a LinkedIn Integration

A connected LinkedIn account does not stay connected on its own. Sessions expire and LinkedIn raises verification steps. This page covers watching for that with webhooks, recognising it when it happens, reconnecting, and restarting the runs that stopped.

Connecting a LinkedIn Identity

Licence compatibility, and every way to connect an account in the first place.

How to tell an integration is invalid

Watch for these signals:

Signal	What it means
Webhook `AUTH_EXPIRED`	Session expired — reconnect (often with `action_to_be_taken: "RETRY_LOGIN"`)
Webhook `AUTH_FAILED`	Authentication failed — retry login or notify the user
Run `error_label` `LK_BAD_COOKIE` · `MISSING_COOKIE` · `RLS_BAD_COOKIE`	Stored cookies are no longer valid
Run `error_label` `LK_LOGIN_ERROR` · `SN_LOGIN_ERROR` · `RLS_LOGIN_ERROR`	Login failed for the identity

Fetch the run with Get Run and read last_error.error_label when a run is BLOCKED. A timezone or VPN mismatch is a common cause of login failures — see Timezone & VPN Settings.

Monitor integration status with webhooks

LinkedIn integrations have a lifecycle that you can monitor in real-time using webhooks. Whether the integration was created through user interaction, frontend operations, or API calls, webhooks provide instant notifications about status changes. Webhooks send HTTP requests to your platform when integration events occur, allowing you to:

React immediately to authentication issues
Notify users about account status changes
Trigger automated responses (e.g., resync flows)
Monitor integration health proactively

Setup Process

Configure Your Webhook URL

Configure a webhook URL in the developer section of your Edges workspace.

Webhook URL Requirements:

Must be HTTPS (e.g., https://your-domain.com/webhooks)
Supports extended URLs with basic auth, ports, and query parameters (up to 1024 characters)
Example: https://user:pass@your-website.com:8080/webhooks/edges/linkedin-integration?foo=bar

You can also add up to 10 custom headers (e.g., API keys) that will be included with each webhook call.

Implement Your Webhook Handler

Each LinkedIn integration event triggers a POST request to your configured URL with this JSON payload:

{
  "event_uid": "<string>",
  "event_type": "integration",
  "event": "AUTH_SUCCESS" | "AUTH_PENDING" | "AUTH_FAILED" | "AUTH_EXPIRED" | "AUTH_UPDATED" | "DELETED",
  "timestamp": <POSIX timastamp as float>,
  "data": {
    "identity_uid": "<string>",
    "integration_permalink": "linkedin",
    "workspace_uid": "<string>",
    "name": null | "<string>",
    "level": null | "Classic" | "Sales Navigator" | "Premium" | "Recruiter Lite",
    "setup_source": null | "MANUAL" | "EXTENSION" | "SHARED" | "API",
    "reason": null | "<string>",
    "action_to_be_taken": null | "CONTACT_SUPPORT" | "RETRY_LOGIN" | "RETRY_CHECKPOINT"
  }
}

Field Explanations

Field	Description
`event_type`, `event`	The type and nature of the integration event
`data`	Standard integration information (see API reference)
`reason`	Cause of the event (especially relevant for `AUTH_EXPIRED`)
`action_to_be_taken`	Recommended next step for handling the event

Event Types

Event	Description	Typical Action
`AUTH_SUCCESS`	Integration successfully authenticated	Continue normal operations
`AUTH_PENDING`	Authentication in progress	Wait for completion
`AUTH_FAILED`	Authentication failed	Retry or notify user
`AUTH_EXPIRED`	Authentication expired	Trigger resync flow
`AUTH_UPDATED`	LinkedIn account level change (Classic, Sales Navigator,…)	Retry or notify user
`DELETED`	Integration was removed (for example via Delete an Identity’s Integration)	Remove cached credentials, stop jobs using this integration

Use Cases

1. Handle Expired Sessions

When you receive an AUTH_EXPIRED event with action_to_be_taken: "RETRY_LOGIN", you can:

Trigger immediate resync via API call
Notify users to re-authenticate
Pause dependent workflows until resolved

When using the native login workflow, users complete authentication asynchronously. The AUTH_SUCCESS event confirms when setup is complete.

Best Practices:

Ensure your webhook endpoint handles POST requests and JSON payloads
Implement proper error handling and logging
Consider verifying webhook authenticity (e.g., via headers)
Respond quickly to webhook requests (within 5 seconds)

Reconnect the integration

Managing Chrome sessions

Use Edges’s Chrome Extension to automatically sync cookies, useful for testing purposes.
If you’re using multiple LinkedIn accounts on the same browser, you must create separate Chrome profiles:
- Click your Chrome profile icon > Add a new profile.
- Name it according to the LinkedIn account (e.g., “Account B”).
- Log in to Edges and LinkedIn within this new session.

Updating cookies for Account A while logged into Account B can lead to mismatches and errors.

Refreshing cookies

Cookies need refreshing if:

You log out of LinkedIn
LinkedIn expires or changes cookies
LinkedIn restricts the account due to excessive activity

Regular activity and following Smart Limits guidelines help prevent restrictions.

How to refresh cookies via API

To refresh accounts via API, use the Connect an Identity’s Integration endpoint by passing the updated li_at and/or li_a cookie values:

If you build your own Chrome Extension, you should refresh cookies every 2 hours or so.

Here’s a code example for a Chrome Extension that runs in the background using alarms:

/**
 * Alarm to update cookies every X minutes.
 */
chrome.alarms.onAlarm.addListener(() => {
  // Ensure updateTokensHandle() is defined elsewhere in your code
  return updateTokensHandle();
});

// Set up the alarm when the extension is installed
chrome.runtime.onInstalled.addListener(async ({ reason }) => {
  const periodDurationMinutes = 120; // Every 2 hours

  // Create an alarm that will trigger every `periodDurationMinutes`
  await chrome.alarms.create("updateToken", {
    periodInMinutes: periodDurationMinutes,
  });

  console.log(
    "Alarm created to update token every " + periodDurationMinutes + " minutes"
  );
});

Complete source code is available on GitHub.

You can also reconnect through native LinkedIn login (email and password). If LinkedIn presents a checkpoint, use the Checkpoint endpoint.

Runs that blocked while it was invalid

BLOCKED is not terminal. After the integration is valid again, resume the run.

Reconnect before you resume. Resuming a run whose identity is still invalid consumes a retry and blocks again immediately.

See Recovering a Blocked Run for the full cause → recovery table (LK_BAD_COOKIE, login errors, and more). When connecting a LinkedIn account natively (with username and password), you may hit one of the errors below. Each row gives the message you’ll see, the status code, and how to resolve it.

Common error cases

Scenario	Message	Status	Error
Invalid credentials	Username or password invalid.	400	`INVALID_CREDENTIALS` _{Double-check your LinkedIn username and password. See authentication endpoint}
Password reset needed	The account is locked, you need to request a password reset.	424	`REQUEST_PASSWORD_RESET` _{Request a password reset on LinkedIn.}
Google login not supported	Username or password invalid.	400	`INVALID_CREDENTIALS` _{Google login is not supported. Use “Forgot password” on LinkedIn to set a password and use that for login.}
Checkpoint code invalid	Code invalid.	400	`INVALID_CODE` _{The checkpoint (2FA/SMS/email) code is incorrect. Try again. See checkpoint endpoint}
In-app challenge pending	Waiting for user to validate in_app_challenge	500	`IN_APP_CHALLENGE_PENDING` _{Complete the challenge in your LinkedIn app.}
In-app challenge expired	In_app_challenge expired. Please retry the whole process by sending credentials again on /authenticate	500	`IN_APP_CHALLENGE_EXPIRED` _{Start the login process again.}
2FA expired	2FA expired. Please retry the whole process by sending credentials again on /authenticate	500	`2FA_VALIDATION_EXPIRED` _{Start the login process again.}
Failed IP attribution	Could not login the account.	500	`LOGIN_ACCOUNT_500_ERROR` _{Retry logging in. This is a LinkedIn-side issue.}
IP allocation error	IP allocation error. Please retry again in 5 minutes or contact support.	400	`IP_ATTRIBUTION_ERROR_400` _{Wait 5 minutes and try again, or contact support.}
IP allocation conflict	IP allocation error. Please retry again in 5 minutes or contact support.	409	`IP_ATTRIBUTION_CONFLICT_409` _{Wait 5 minutes and try again, or contact support.}
IP rate limit exceeded	Rate limit exceeded IP attribution, please try again in five (5) minutes or contact the support.	429	`IP_ATTRIBUTION_RATE_LIMIT_429` _{Wait 5 minutes and try again, or contact support.}
No IP available in timezone	No IP available in this timezone. Update your timezone to a neighbouring one or contact support.	400	`IP_TIMEZONE_NOT_SUPPORTED_400` _{Change your timezone in Edges or contact support.}
Captcha challenge	Error while resolving the challenge, the Captcha challenge seem to be pending. Re-send username and password to overcome this.	500	`CAPTCHA_CHALLENGE_ERROR` _{Retry the authentication with your credentials.}
Unsupported challenge	Unsupported challenge identified, please contact the support and provide it with the identity_uid so we can address it.	500	`UNSUPPORTED_CHALLENGE` _{Contact support with your identity_uid.}
Simple challenge failed	Error while solving challenge, retry in 5 minutes, if it persists contact support.	500	`LOGIN_SIMPLE_CHALLENGE` _{Wait and retry, or contact support.}
Checkpoint missing data	Error while solving the challenge, retry the whole process by sending credentials to /authenticate again	500	`CHECKPOINT_MISSING_DATA` _{Start the login process again.}
User management not permitted	User management via the API is not permitted for the current workspace, activate the option on settings	403	`CREATE-ONE-ACCOUNT_403_FORBIDDEN` _{Enable user management in your workspace settings.}
Identity already exists	An identity with the same Linkedin ID already exists.	409	`CREATE_OR_UPDATE_ACCOUNT_409_CONFLICT` _{Use a different LinkedIn account or identity.}
Account already exists on identity	An account already exist on this identity	409	`CREATE_OR_UPDATE_ACCOUNT_409_CONFLICT`
Account link change	Please note that your LinkedIn integration is different from the one that has already been synchronized on this identity.	409	`CREATE_OR_UPDATE_ACCOUNT_409_CONFLICT` _{Use the same LinkedIn account as previously connected.}
Other errors	Error while synchronizing your account, please retry again or contact the support.	500	- _{Retry or contact support.}

Notes & recommendations

Google Login: If your LinkedIn account uses Google login, you must set a password on LinkedIn (via “Forgot password”) to use native login.
IP/Location Issues: Many errors are related to IP allocation or location mismatches. Make sure your timezone and country settings in Edges match your actual login location.
Challenge/2FA: If you receive a challenge (SMS, email, in-app), complete it promptly. If it expires, restart the login process.
Contact Support: For persistent or unclear errors, contact support and provide your identity_uid for faster resolution.

Connect with username & password

Endpoint reference for the native login flow.

Resolve a checkpoint

Endpoint reference for clearing a verification step.

Start here

Identities

Running actions

Limits

Troubleshooting

LinkedIn specifics

SDKs & integrations

Build with Edges

Monitoring & Recovering a LinkedIn Integration

Connecting a LinkedIn Identity

How to tell an integration is invalid

Monitor integration status with webhooks

Setup Process

Field Explanations

Event Types

Use Cases

1. Handle Expired Sessions

Reconnect the integration

Managing Chrome sessions

Refreshing cookies

How to refresh cookies via API

Runs that blocked while it was invalid

Common error cases

Notes & recommendations

Connect with username & password

Resolve a checkpoint

Connecting a LinkedIn Identity

​How to tell an integration is invalid

​Monitor integration status with webhooks

​Setup Process

Field Explanations

​Event Types

​Use Cases

​1. Handle Expired Sessions

​2. Monitor Native Login Workflow

​Reconnect the integration

​Managing Chrome sessions

​Refreshing cookies

​How to refresh cookies via API

​Runs that blocked while it was invalid

​Troubleshooting login errors

​Common error cases

​Notes & recommendations

Connect with username & password

Resolve a checkpoint

How to tell an integration is invalid

Monitor integration status with webhooks

Setup Process

Event Types

Use Cases

1. Handle Expired Sessions

2. Monitor Native Login Workflow

Reconnect the integration

Managing Chrome sessions

Refreshing cookies

How to refresh cookies via API

Runs that blocked while it was invalid

Troubleshooting login errors

Common error cases

Notes & recommendations