Skip to main content

Webhooks

Server-based applications may receive connection events via Webhooks.

Webhooks are enabled on demand, please contact us to enable it. You will need to provide us with your webhooks url. Please note that you must be on a premium plan to have access to Webhooks.

List of webhooks​

SyncInstitution​

A SyncInstitution webhook can be sent to your receiving endpoint via a POST when an account successfully syncs. The account refresh happens once daily, or on demand (when you POST to /institutions/:id/sync endpoint). The webhook is triggered at the end of the process if it’s successful. It would have the following schema in the body JSON:

{
  hook: "SyncInstitution",
  user: { id, loginName },
  institution: { id, name, type }
}

SyncError​

A SyncError webhook can be sent to your receiving endpoint via a POST when an account runs into an error during sync. It would have the following schema in the body JSON:

{
  hook: "SyncError",
  user: { id, loginName },
  institution: { id, name, type },
  error: "LoginFailedError|SecurityQuestionError|TemporaryFailureError|UnhandledConnectorError|UnknownConnectorError"
}
  • LoginFailedError: indicates an issue with the account credentials (username, password, token, key, etc.) and requires a reconnection (Reconnect an account). User will need to provide new credentials before the account could be synced again.
  • SecurityQuestionError: indicates a need of user input (usually for security question or 2FA verification) in order to connect the account successfully. This also requires a Reconnect process where user would re-enter credentials and be prompted for the verification process.
  • TemporaryFailureError: indicates a temporary failure while syncing the account. When encountering this error, an automatic retry will be scheduled, and there is no need to take action. But if this error keeps happening for the same account, it is advised to contact us with the account id for investigation.
  • UnhandledConnectorError: indicates an unhandled failure while syncing the account. When encountering this error, it is advised to contact us with the account id for investigation.
  • UnknownConnectorError: indicates an unknown failure while syncing the account. When encountering this error, it is advised to contact us with the account id for investigation.
  • UserActionRequiredError: There is a pending action at the financial institution (usually new terms of service, reset password prompt or some administrative task). User must log in to the financial institution, complete the pending action there and trigger a sync.