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):

Element	Type	Description
`event`	string	Unique event name for the webhook. Set to `login`.
`connectionUuid`	string	The connection uuid associated with the webhook. Automatically assigned by Accounting Data as a Service™. See connections for more details.
`businessUuid`	string	The business uuid associated with the webhook. See businesses for more details.
`businessName`	string	The business name associated with the webhook. See businesses for more details.
`serviceName`	string	The 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):

Element	Type	Description
`event`	string	Unique event name for the webhook. Set to `auth`.
`connectionUuid`	string	The connection uuid associated with the webhook. Automatically assigned by Accounting Data as a Service™. See connections for more details.
`businessUuid`	string	The business uuid associated with the webhook. See businesses for more details.
`businessName`	string	The business name associated with the webhook. See businesses for more details.
`serviceName`	string	The name of the connected integration. See possible enum values.
`serviceAccountRef`	object	Object containing the account id and subsidiary or sub account id for the connection

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):

Element	Type	Description
`event`	string	Unique event name for the webhook. Set to `connectionStatus`.
`connectionUuid`	string	The connection uuid associated with the webhook. Automatically assigned by Accounting Data as a Service™. See connections for more details.
`businessUuid`	string	The business uuid associated with the webhook. See businesses for more details.
`businessName`	string	The business name associated with the webhook. See businesses for more details.
`serviceName`	string	The name of the connected integration. See possible enum values.
`oldStatus`	string	The previous connection before the event occurred. See possible enum values.
`newStatus`	string	The new connection after the event occurred. See possible enum values.
`message`	string	A friendly disconnected reason message.
`disconnectReason`	string	The reason a connection was disconnected. See possible enum values.
`effectiveOn`	string	The date and time the connection was disconnected. See date format for more details.
`serviceAccountRef`	object	Object containing the account id and subsidiary or sub account id for the connection

serviceAccountRef Object may include the following elements:

Element	Type	Description
`id`	string	Account id for the connection
`entityRef.id`	string	Sub account or Subsidiary account id for the connection

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",
    "serviceAccountRef": {
      "id": "DEV",
      "entityRef": {
        "id": "100"
      }
    }
	},
	"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",
    "serviceAccountRef": {
      "id": "DEV",
      "entityRef": {
        "id": "100"
      }
    }
	},
	"requestId": "a3b4fc83-3e24-41aa-ba99-13cab09b0b7a"
}