Skip to main content
Use one of the following methods to find out when your user’s account has connected successfully to Seam through your app:
  • If you’ve redirected your app to the Connect Webview, poll or use a webhook to determine when the Connect Webview has completed successfully. You can then retrieve the device or ACS associated with the newly-connected account.
  • If you’ve embedded the Connect Webview in an iframe, use event listening to determine when to close the iframe. You can then retrieve the device or ACS associated with the newly-connected account.
You do not need to delete a Connect Webview once a user completes it. Instead, you can simply ignore completed Connect Webviews.

​
Polling

Use the connect_webview_id to retrieve the Connect Webview instance. You can check the following properties:
PropertyValue when connected successfully
statusauthorized
login_successfultrue
Also, once the connection is successful, the connect_webview object includes a connected_account_id. Code: 
const updatedConnectWebview = await seam.connectWebviews.get({
  connect_webview_id: connectWebview.connect_webview_id,
})

curl -X 'GET' \
  'https://connect.getseam.com/connect_webviews/get' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer ${SEAM_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
  \"connect_webview_id\": \"${connect_webview_id}\"
}"

updated_connect_webview = seam.connect_webviews.get(created_connect_webview.connect_webview_id)

updated_connect_webview = seam.connect_webviews.get(
  connect_webview_id: connect_webview.connect_webview_id
)

$updated_connect_webview = $seam->connect_webviews->get(
  connect_webview_id: $connect_webview->connect_webview_id
);

var updatedConnectWebview = seam.ConnectWebviews.Get(
  connectWebviewId: connectWebview.connectWebviewId
);
Output: 
{
  connect_webview_id: '12345678-1234-1234-1234-123456789012',
  status: 'authorized',
  login_successful: true,
  connected_account_id: '11111111-1111-1111-1111-222222222222',
  ...
}

{
  "connect_webview": {
    "connect_webview_id": "12345678-1234-1234-1234-123456789012",
    "status": "authorized",
    "login_successful": true,
    "connected_account_id": "11111111-1111-1111-1111-222222222222",
    ...
  },
  "ok": true
}

ConnectWebview(
  connect_webview_id='12345678-1234-1234-1234-123456789012',
  status='authorized',
  login_successful=True,
  connected_account_id='11111111-1111-1111-1111-222222222222',
  ...
)

<
  Seam::ConnectWebview:0x00438
    connect_webview_id="12345678-1234-1234-1234-123456789012"
    status="authorized"
    login_successful=true
    connected_account_id="11111111-1111-1111-1111-222222222222"
    ...
>

{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "status": "authorized",
  "login_successful": true,
  "connected_account_id": "11111111-1111-1111-1111-222222222222",
  ...
}

{
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "status": "authorized",
  "login_successful": true,
  "connected_account_id": "11111111-1111-1111-1111-222222222222",
  ...
}

​
Webhook

When Seam successfully establishes the connection to the user’s device or ACS account, Seam emits a connected_account.connected event. This event includes a connect_webview_id property. To avoid polling, use a Seam webhook to monitor for a connected_account.connected event with a connect_webview_id that matches the connect_webview_id of the appropriate Connect Webview instance. Note that the connected_account.connected event also includes a connected_account_id property. For more information, see Webhooks. 
{
  "event_id": "22222222-3333-4444-5555-666666666666",
  "event_type": "connected_account.connected",
  "connected_account_id": "11111111-1111-1111-1111-222222222222",
  "connect_webview_id": "12345678-1234-1234-1234-123456789012",
  "occurred_at": "2024-07-17T05:01:53.157Z",
  ...
}

​
Event Listening

When you host a Connect Webview in an HTML iframe, the iframe uses window.parent.postMessage to send messages to the parent window that is hosting the iframe. window.parent.postMessage is a cross-origin communication mechanism available in web browsers. Register an event listener for the parent window containing the iframe to monitor for message events. Specifically, listen for a connect_webview.login_succeeded event. This event indicates that Seam has successfully established the connection to the user’s device or ACS account. A connect_webview.login_failed event indicates that the account connection did not complete successfully. For example: 
window.addEventListener(
  'message',
  (event) => {
    if (event.data?.event?.event_type === 'connect_webview.login_succeeded') {
      // Do something.
    }
  },
  false,
)
Once you have received a connect_webview.login_succeeded event, you can use webhooks or listen for any of the following useful connection-related events:
EventDescription
connected_account.createdA connected account has been imported into your Seam workspace.
connected_account.connectedSeam has established connection to or is reconnected to a connected account.
connected_account.completed_first_syncSeam has finished the first sync of a connected account, and the corresponding devices or systems are now available.
device.addedA device was added to Seam or was re-added to Seam after having been removed.
device.connected

The status of a device changed from offline to online. That is, the device.properties.online property changed from false to true.
Note that some devices operate entirely in offline mode, so Seam never emits a device.connected event for these devices.