Connection Webhooks

You will receive notifications via a webhook whenever there are new events associated with a Connection or its status.

New Connection

The New Connection event is fired when a new connection is created (i.e the user has opened the accounting service provider login page).

Event Object

The webhook payload is sent in standard JSON format and contains an event object with the following information represented by key-value pairs (KVPs):

ElementTypeDescription
eventstringUnique event name for the webhook. Set to login.
connectionUUidstringThe connection uuid associated with the webhook. Automatically assigned by Railz. See connections for more details.
businessUuidstringThe business uuid associated with the webhook. See businesses for more details.
businessNamestringThe business name associated with the webhook. See businesses for more details.
serviceNamestringThe name of the connected integration. See possible enum values.

Authentication Completed

The Authentication Completed event is fired when a connection is successful.

Event Object

The webhook payload is sent in standard JSON format and contains an event object with the following information represented by key-value pairs (KVPs):

ElementTypeDescription
eventstringUnique event name for the webhook. Set to auth.
connectionUUidstringThe connection uuid associated with the webhook. Automatically assigned by Railz. See connections for more details.
businessUuidstringThe business uuid associated with the webhook. See businesses for more details.
businessNamestringThe business name associated with the webhook. See businesses for more details.
serviceNamestringThe name of the connected integration. See possible enum values.

Connection Disconnected

The Connection Disconnected event is fired when a connection status has changed to a disconnected state (e.g. inactive).

Event Object

The webhook payload is sent in standard JSON format and contains an event object with the following information represented by key-value pairs (KVPs):

ElementTypeDescription
eventstringUnique event name for the webhook. Set to connectionStatus.
connectionUuidstringThe connection uuid associated with the webhook. Automatically assigned by Railz. See connections for more details.
businessUuidstringThe business uuid associated with the webhook. See businesses for more details.
businessNamestringThe business name associated with the webhook. See businesses for more details.
serviceNamestringThe name of the connected integration. See possible enum values.
oldStatusstringThe previous connection before the event occurred. See possible enum values.
newStatusstringThe new connection after the event occurred. See possible enum values.
messagestringA friendly disconnected reason message.
disconnectReasonstringThe reason a connection was disconnected. See possible enum values.
effectiveOnstringThe date and time the connection was disconnected. See date format for more details.

Example Connection Event Objects

{
  "data": {
    "event": "login",
    "connectionUuid": "CON-0a4e97aa-7a77-bbbb-00aa-b1b1001aa00",
    "businessUuid": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "businessName": "ABC Company",
    "serviceName": "quickbooks"
	},
	"requestId": "a3b4fc83-3e24-41aa-ba99-13cab09b0b7a"
}
{
  "data": {
    "event": "auth",
    "connectionUuid": "CON-0a4e97aa-7a77-bbbb-00aa-b1b1001aa00",
    "businessUuid": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "businessName": "ABC Company",
    "serviceName": "quickbooks"
	},
	"requestId": "a3b4fc83-3e24-41aa-ba99-13cab09b0b7a"
}
{
  "data": {
    "event": "connectionStatus",
    "connectionUuid": "CON-0a4e97aa-7a77-bbbb-00aa-b1b1001aa00",
    "businessUuid": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "businessName": "ABC Company",
    "serviceName": "quickbooks",
    "oldStatus": "active",
    "newStatus": "disconnected",
    "message": "Refresh token expired for quickbooks, reconnection required",
    "disconnectReason": "expiredCredentials",
    "effectiveOn": "2021-05-07T10:18:29.985Z"
	},
	"requestId": "a3b4fc83-3e24-41aa-ba99-13cab09b0b7a"
}

Example Connection Event Objects

{
  "data": {
    "event": "login",
    "connectionId": "CON-0a4e97aa-7a77-bbbb-00aa-b1b1001aa00",
    "businessName": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "serviceName": "quickbooks"
	},
	"requestId": "a3b4fc83-3e24-41aa-ba99-13cab09b0b7a"
}
{
  "data": {
    "event": "auth",
    "connectionId": "CON-0a4e97aa-7a77-bbbb-00aa-b1b1001aa00",
    "businessName": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "serviceName": "quickbooks"
	},
	"requestId": "a3b4fc83-3e24-41aa-ba99-13cab09b0b7a"
}
{
  "data": {
    "event": "connectionStatus",
    "connectionId": "CON-0a4e97aa-7a77-bbbb-00aa-b1b1001aa00",
    "businessName": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "serviceName": "quickbooks",
    "oldStatus": "active",
    "newStatus": "disconnected",
    "message": "Refresh token expired for quickbooks, reconnection required",
    "disconnectReason": "expiredCredentials",
    "effectiveOn": "2021-05-07T10:18:29.985Z"
	},
	"requestId": "a3b4fc83-3e24-41aa-ba99-13cab09b0b7a"
}