> ## Documentation Index
> Fetch the complete documentation index at: https://docs.edges.run/llms.txt
> Use this file to discover all available pages before exploring further.
# Monitoring & Recovering a LinkedIn Integration
> Watch a LinkedIn integration with webhooks, tell when it has gone invalid, reconnect it, and recover the runs that blocked.
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.
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](/v1/api/runs/get) 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](/v1/identities/add-manage-identities#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 a webhook URL in the [developer section of your Edges workspace](https://app.edges.run/settings/developers).
**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.
Each LinkedIn integration event triggers a POST request to your configured URL with this JSON payload:
```json theme={null}
{
"event_uid": "",
"event_type": "integration",
"event": "AUTH_SUCCESS" | "AUTH_PENDING" | "AUTH_FAILED" | "AUTH_EXPIRED" | "AUTH_UPDATED" | "DELETED",
"timestamp": ,
"data": {
"identity_uid": "",
"integration_permalink": "linkedin",
"workspace_uid": "",
"name": null | "",
"level": null | "Classic" | "Sales Navigator" | "Premium" | "Recruiter Lite",
"setup_source": null | "MANUAL" | "EXTENSION" | "SHARED" | "API",
"reason": null | "",
"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](/v1/api/integrations/get)) |
| `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](/v1/api/integrations/delete)) | 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
#### 2. Monitor Native Login Workflow
When using the [native login workflow](/v1/identities/linkedin#send-your-user-a-login-link), 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**](/v1/linkedin/limits) guidelines help prevent restrictions.
#### How to refresh cookies via API
To refresh accounts via API, use the [Connect an Identity's Integration](/v1/api/integrations/connect) 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`:
```jsx theme={null}
/**
* 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](https://github.com/edgesrun/chrome-extension-skeleton).
You can also reconnect through [native LinkedIn login](/v1/api/linkedin/authentication) (email and password). If LinkedIn presents a checkpoint, use the [Checkpoint](/v1/api/linkedin/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](/v1/runs/recover-blocked-run) for the full cause → recovery table (`LK_BAD_COOKIE`, login errors, and more).
## Troubleshooting login errors
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](/v1/api/linkedin/authentication) |
| 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](/v1/api/linkedin/checkpoint) |
| 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](https://app.edges.run/settings/users/parameters) | 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.
Endpoint reference for the native login flow.
Endpoint reference for clearing a verification step.