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 the quickest way for you to receive the connection information.

Railz sends an event when a new connection is created (i.e the user has opened the accounting service provider login page).

The payload for this event will contain all the connection information. You can identify this specific event by the property "event":"login".

{
  "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"
}

After receiving the New Connection event, you will later receive an Authentication Completed event (if enabled), after a successful connection to the accounting service provider.

📘

You can consolidate all events by tracking the received connectionId or businessName and serviceName combination.

Authentication Completed

The Authentication Completed event is the quickest way for you to receive confirmation that a connection was successful.

Railz sends an event when a connection is successful.

The payload for this event will contain all the connection information. You can identify this specific event by the property "event":"auth".

{
  "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"
}

📘

You can consolidate all events by tracking the received connectionId or businessName and serviceName combination.

Connection Disconnected

The Connection Disconnected event is the quickest way for you to receive updates about a disconnected connection.

Railz sends an event when a connection status has changed to a disconnected state (e.g. inactive). The Connection Status Changed event is not triggered for new connections. To subscribe to a new connection event, see Event: New Connection.

The payload for this event will contain all the connection information. You can identify this specific event by the property "event":"connectionStatus".

{
  "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"
}

📘

See Connections for all possible connection statuses and disconnect reasons.

📘

You can consolidate all events by tracking the received connectionId or businessName and serviceName combination.