Connection flow for an Integrated account

This document describes the flow of events that happen when an integrated account is connected. This is useful for understanding the different steps involved in the connection process and for debugging any issues that may arise during the connection process.

end-user refers to the user who is connecting their account.

Integrated account is created: When an integrated account is created, Truto will send an integrated_account:created webhook event. This event will contain the integrated account as the payload. When an existing account is reauthorized, Truto sends integrated_account:updated instead, and the remaining steps run in the same order.
Post install steps run: Post install steps are requests, transformations and other steps that are defined on the integration to make the Unified and Proxy APIs work properly. These steps are run after the integrated account is created. If any of these steps fail, Truto will send an integrated_account:post_install_error webhook event. This event will contain the integrated account as the payload, the end-user will be notified on the connection screen and Truto Link SDK will throw an error. Post install steps are not defined on all the integrations.
Connection validation steps run: Connection validation steps are Unified and Proxy API requests that are defined on the integration to make sure that the connection is valid and has the necessary permissions required for making the API calls. They run only if the post install steps succeeded; when post install fails, validation is skipped. If any of these steps fail, Truto will send an integrated_account:validation_error webhook event. This event will contain the integrated account as the payload, the end-user will be notified on the connection screen and Truto Link SDK will throw an error. Connection validation steps are not defined by Truto and can be configured by you in the installed integration details page.
Integrated account is activated: The integrated account is now ready to use -- Unified and Proxy API calls be made against this integrated account, Truto will send an integrated_account:active webhook event. This event will contain the integrated account as the payload. This event is sent only after the post install and connection validation steps succeed. If either fails, the account keeps its post_install_error or validation_error status and no integrated_account:active event is sent.
Post connect form (RapidForm) submitted: If a post connect form (RapidForm) is defined on the installed integration, Truto will send an integrated_account:post_connect_form_submitted webhook event when the user submits the RapidForm on the connection screen. This event will contain the integrated account as the payload. This event is sent after the integrated account is activated.

Warning

If the post install steps or connection validation steps fail, the integrated account is not deleted automatically. Once the cause is fixed, recover it without reconnecting: POST /integrated-account/run-post-install-actions with { "id": "<integrated-account-id>" } reruns post install and validation; on success the account returns to active and Truto sends integrated_account:active. POST /integrated-account/<integrated-account-id>/validate reruns validation alone. It moves an account out of validation_error only, back to active with integrated_account:active; an account in post_install_error keeps that status. It returns 404 when the integration has no validation step. You can also delete the integrated account.

When the connection fails before an account exists

Some attempts fail before Truto has an integrated account to attach events to: the end user cancels on the provider's consent screen or the provider refuses authorization, the OAuth token exchange fails, or Truto can't start or save the connection (for example, the integration has no OAuth app credentials configured in the environment). Truto then sends a link_token:connection_error webhook event instead of any integrated_account:* event. On a reauthorization it fires when the attempt fails before the existing account is updated.

The event's payload describes the attempt, not an account:

environment_id — the environment the link token belongs to.
tenant_id — the tenant the link token was created for, or null.
environment_integration_id — the installed integration being connected, or null when the failure came before one was resolved.
integration — the integration's name.
error — a human-readable message, for example the provider's refusal reason.
redirect_uri — the redirect_uri from the link token, or null.
context — the context you set when creating the link token, or null. Values the end user typed into the connection UI are not included.
integrated_account_id, environment_unified_model_id, scopes, persist_previous_context, truto_static_gate_id, region — the fields you sent to POST /link-token, each null when you didn't send it. integrated_account_id is set when the failed attempt was a reauthorization.

{
  "id": "<event-id>",
  "event": "link_token:connection_error",
  "payload": {
    "environment_id": "<environment-id>",
    "tenant_id": "acme-1",
    "environment_integration_id": "<environment-integration-id>",
    "integration": "hubspot",
    "error": "invalid_grant",
    "redirect_uri": "https://example.com/truto/callback",
    "context": null,
    "integrated_account_id": null,
    "environment_unified_model_id": null,
    "scopes": null,
    "persist_previous_context": null,
    "truto_static_gate_id": null,
    "region": null
  },
  "environment_id": "<environment-id>",
  "created_at": "2026-11-02T10:15:00.000Z",
  "webhook_id": "<webhook-id>"
}

An expired or invalid link token sends no event, because Truto cannot tell which environment it belongs to. Once an account exists, failures are reported with integrated_account:post_install_error and integrated_account:validation_error as described above.