Data Sync Webhooks

Railz offers two data synchronized webhook events.

The Data Synchronized event is fired when a data sync (initial and/or recurring) is completed. This webhook event should be used to get informed for when the business has completed syncing with all the event types within 1 webhook.
The Data Per Type event is fired for the selected data types you have indicated within our Railz Dashboard. Once the data has completed syncing for the specified data type, you will receive the webhook event. Note: that if you manually select all of the data types, then you will receive a webhook event for each individual type. See example below.

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 `data`.
`connectionId`	string	The connection id associated with the webhook. Automatically assigned by Railz. See connections 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.
`requests`	array / object	Data sync request objects representing the status of each synchronized.
`dataSyncType`	string	Data synchronization options. See possible enum values.
`sandbox`	boolean	Represents if its a webhook in sandbox environment or production environment.

Each object in the requests array may include the following elements:

Element	Type	Description
`id`	string	Unique data sync request ID. Automatically assigned by Railz.
`request`	string	The data type associated with the webhook. See /data/dataTypes endpoint for all possible enum values.
`startDate`	string	The period start date for the synchronized data in the format `YYYY-MM-DD`.
`endDate`	string	The period end date for the synchronized data in the format `YYYY-MM-DD`.
`reportFrequency`	string	The timeframe associated with the synchronized data. Possible values: `year`, `quarter`, `month`.
`status`	string	The status of the data sync. Possible values: `success`, `failed`, `empty`. See data sync statuses for more details.

Payload Types

For data webhook events, users can choose between two types of payloads: Full Payload and Simple Payload.

Full Payload

A comprehensive payload containing detailed information about each sync request.

Example Full Data Sync Event Object

{
  "data": {
    "event": "data",
    "connectionId": "CON-0a4e97aa-7a77-bbbb-00aa-b1b1001aa00",
    "businessName": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "serviceName": "quickbooks",
    "dataSyncType": "manualSync",
    "requests": [
      {
        "id": "60e61e0c53031851d54b4f82",
        "request": "accounts",
        "status": "success"
      },
      {
        "id": "6333539d6d8f1176fd9ac05b",
        "request": "balanceSheets",
        "startDate": "2018-06-01",
        "endDate": "2018-09-30",
        "reportFrequency": "year",
        "status": "success"
      },
      {
        "id": "6333539e6d8f1176fd9ac07f",
        "startDate": "2018-06-01",
        "endDate": "2018-09-30",
        "reportFrequency": "quarter",
        "status": "failed"
      },
      {
        "id": "6034449e6d8f1176fd9ac09a",
        "request": "incomeStatements",
        "startDate": "2018-04-01",
        "endDate": "2018-04-30",
        "reportFrequency": "month",
        "status": "empty"
      },
      {
        "id": "6035559e6d8f1176fd9ac0b1",
        "request": "cashflowStatements",
        "startDate": "2020-03-01",
        "endDate": "2020-03-31",
        "reportFrequency": "month",
        "status": "success"
      }
    ]
  },
  "requestId": "a3b4fc83-3e24-41aa-ba99-13cab09b0b7a"
}

Simple Payload

A summarized payload providing the status of sync requests without detailed information.

Example Simple Webhook Payload

{
  "data": {
    "connectionId": "CON-0a4e97aa-7a77-bbbb-00aa-b1b1001aa00",
    "businessName": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "serviceName": "sageIntacct",
    "event": "data",
    "id": 26243,
    "serviceAccountRef": {
      "id": "DEV",
      "subsidiaryRef": {
        "id": "100"
      }
    },
    "requests": {
      "bills": {
        "success": 5,
        "empty": 3,
        "failed": 0
      },
      "billPaymentRequests": {
        "success": 1,
        "empty": 7,
        "failed": 0
      },
      "businessInfo": {
        "success": 1,
        "empty": 0,
        "failed": 0
      },
      "taxRates": {
        "success": 1,
        "empty": 0,
        "failed": 0
      }
    },
    "dataSyncType": "fullSync",
    "sandbox": false,
    "connectionUuid": "CON-0a4e97aa-7a77-bbbb-00aa-b1b1001aa00"
  },
  "requestId": "a3b4fc83-3e24-41aa-ba99-13cab09b0b7a"
}

Choosing the Payload Type

In the Railz Dashboard, users can select their preferred payload type for data synchronization under the webhook configuration settings:

Full Payload: Provides detailed information for each sync request.
Simple Payload: Provides a summarized status for sync requests.

Refer to the screenshot below for configuring webhook payload types in the Railz Dashboard.

Example Data per type Sync Event Object

{
  "data": {
    "businessName": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "businessUuid": "BIZ-d6b1c7d3-fe41-4447-ae72-3814b78b5142",
    "connectionId": "CON-8ed8f748-0e52-42f8-b7d9-50b121d57d20",
    "serviceName": "sageIntacct",
    "event": "dataPerType",
    "requestType": "billPaymentRequests",
    "dataSyncType": "fullSync",
    "sandbox": false,
    "serviceAccountRef": {
      "id": "DEV",
      "subsidiaryRef": {
        "id": "100"
      }
    },
    "requests": [
      {
        "id": "668e94c44f2bb9dff53827b3",
        "request": "billPaymentRequests",
        "startDate": "2017-01-01",
        "endDate": "2017-12-31",
        "status": "empty"
      },
      {
        "id": "668e94c44f2bb9dff53827b4",
        "request": "billPaymentRequests",
        "startDate": "2018-01-01",
        "endDate": "2018-12-31",
        "status": "empty"
      }
    ],
    "connectionUuid": "CON-8ed8f748-0e52-42f8-b7d9-50b121d57d20"
  },
  "requestId": "428ebd8f-7cb2-4fa7-9cdb-00f083044324"
}