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://cdn.jsdelivr.net/npm/@railzai/railz-connect@latest/dist/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.

Parameter	Type	Description
`businessName`	string	Displayed once Railz Connects has loaded. The unique identifier of the business as defined by you or generated by Railz.
`metadata`	array	Displayed 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.

Parameter	Type	Description
`businessName`	string	Displayed once Railz Connects has loaded. The unique identifier of the business as defined by you or generated by Railz.
`metadata`	array	Displayed once Railz connect has loaded. The `metadata` provided by you.
`serviceName`	string	The 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.

Parameter	Type	Description
`businessName`	string	Displayed 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.

Parameter	Type	Description
`error`	object	An error object that contains the `errorCode` and `errorMessage`of the error that was last encountered by the user.
`error.errorCode`	string	The error code and error type that the user encountered.
`error.errorMessage`	string	A 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.