Event Listeners

Railz Connect triggers events according to authentication responses or different UI steps that are presented to the end-user. These events can be listened to by using JavaScript callback functions and can be useful tools for tracing purposes as well as controlling the user experience.

To have the Event Listener enabled in your application, you need to make sure that you have the following parameters added to your Railz Connect script in your application:

<!-- Insert this div where you want Railz Connect to be initialized -->
<div id="railz-connect"></div>


<!-- Start of Railz Connect script -->
<script src="https://connect.railz.ai/v1/railz-connect.js"></script>
<script>
  var widget = new RailzConnect();
  widget.mount({
    parentElement: document.getElementById('railz-connect'),
    widgetId: widgetId,

    // Event Listeners   
    onExit: (event, data) => {
        /**Your code here*/
    },
    onSuccess: (event, data) => {
      /**Your code here*/
    },
    onError: (event, data) => {
      /**Your code here*/
    }
  });
</script>
<!-- End of Railz Connect script -->

onSuccess

Load

The event is called when Railz Connect is initialized and loaded in your application. It sends a load event with the following data as a payload.

ParameterTypeDescription
businessNamestringDisplayed once Railz Connects has loaded. The unique identifier of the business as defined by you or generated by Railz.
metadataarrayDisplayed once Railz connect has loaded. The metadata provided by you.
{
  businessName: "Railz Test",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ]
}

Authorization

The event is called when a user successfully connects to a service provider. It sends an authorization event with the following data as a payload.

ParameterTypeDescription
businessNamestringDisplayed once Railz Connects has loaded. The unique identifier of the business as defined by you or generated by Railz.
metadataarrayDisplayed once Railz connect has loaded. The metadata provided by you.
serviceNamestringThe service name the user connected to a business, e.g. quickbooks
{
  businessName: "Railz Test",
  serviceName: "quickbooks",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ]
}

onExit

This event is called when a user exits Railz Connect regardless of connection success or failure. It sends an exit event with the following data as a payload.

ParameterTypeDescription
businessNamestringDisplayed once Railz Connects has loaded. The unique identifier of the business as defined by you or generated by Railz.
{
  businessName: "Railz Test"
}

onError

This event is called when an error occurs during the connection flow. It sends an error object within each event's payload. Error events are triggered when:

  • A connection was not successful.
  • Generic Railz Connect errors.
  • Timed-out.
ParameterTypeDescription
errorobjectAn error object that contains the errorCode and errorMessageof the error that was last encountered by the user.
error.errorCodestringThe error code and error type that the user encountered.
error.errorMessagestringA developer-friendly representation of the error code.

Load

{
  businessName: "Railz Test",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ],
  error: {
    errorCode: "timeout",
    errorMessage: "Request has timedout."
  }
}

Authorization

{
  businessName: "Railz Test",
    serviceName: "freshbooks",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ],
  error: {
    errorCode: "unauthorizedCredentials",
    errorMessage: "Unable to authorize connection with provided credentials."
  }
}

Timeout

{
  businessName: "Railz Test",
    serviceName: "freshbooks",
  metadata: [
    {
      name: "businessLocation",
      value: "canada",
      webhookLocation: ["header", "body"]
    }
  ],
  error: {
    errorCode: "timeout",
    errorMessage: "Request has timedout."
  }
}

📘

serviceName is optional in timeout error events. A timeout prior to the user selecting a service will not have a serviceName in the event response.


Did this page help you?