Skip to main content
Provider connections are long-lived dependencies on user credentials, provider APIs, and networks. A connection that works today can later fail because access was revoked, credentials expired, permissions changed, or a provider invalidated its authorization. In other words: the universe has entropy, systems fail, and every connection eventually meets its end. So treat reconnection as normal to your product lifecycle rather than something unexpected.

​
Suggested connection lifecycle

Junction provides two webhook events for the connection lifecycle: A typical implementation uses these events to keep the connection experience in sync with Junction:
1

Handle the connection error event

Use user_id or client_user_id to identify the user and data.provider to identify the affected provider. The event also includes an error_type, message, and error_details for diagnosis.Error types are non-exhaustive, so implementations should accept values they do not recognize.
2

Prompt the user to reconnect

Use the event to present a reconnection option at the point that makes sense for your product. Explain that the connection needs attention and provide a way to reconnect it.Follow the Junction Link flow and generate a new Link token for the existing Junction user. The provider can be passed when generating the token to open Link directly to the relevant connection flow.
3

Handle the successful connection event

Use provider.connection.created to recognize that the provider was connected successfully and update your application’s connection experience as appropriate.
For example, an application might display:
Your connection needs attention. Reconnect your device or account to resume syncing.
The exact notification channel, application state, and reconnection experience are up to your implementation.

​
Reconcile connection status

The Get User Connections endpoint returns the current providers for a Junction user, including whether each connection is connected or in an error state. You can use this endpoint when you need to:
  • Confirm the current state before presenting a reconnection prompt.
  • Refresh connection state when a user opens your application.
  • Reconcile your records after webhook delivery or processing failures.
  • Periodically check connection state if that fits your application’s requirements.
How often you reconcile—and whether you do so in response to an event, user activity, or a scheduled process—depends on your product and infrastructure.