Rule types

Use webhooks to build responsive and resilient applications on Codat data

New webhook service available

This page describes the functionality of our legacy webhook offering. Learn more about our new webhook service and see how you can migrate to use it instead.

The following rules can be configured in the Codat Portal to trigger webhook events. These can be use to help your respond to changes in your companies and their data.

Rule	Type	Trigger	Additional data
Company data connection status changed	`DataConnectionStatusChanged`	A data connection's status changes.	`dataConnectionId`, `platformKey`, `newStatus`, `oldStatus`
New company synchronized	`New company synchronized`	All datasets created during the initial sync of a company are completed.
Data sync completed	`Data sync completed`	Data synchronization is successfully completed in full for a specific data type. A notification is generated for each `dataType` as the sync completes.	`dataType`, `datasetId`
Dataset data changed	`Dataset data changed`	A dataset synchronization has completed and updated Codat's data cache through the creation of new records or a change to existing records. A notification is generated for each `dataType` as the sync completes.	`dataType`, `datasetId`
Dataset status has changed to an error state	`Data Sync Status Changed To Error`	The synchronization of a dataset fails.	`dataType`, `datasetStatus`, `datasetId`
Push operation status has changed	`Push Operation Status Changed()`	A write operation's status changes.	`dataType`, `status`, `pushOperationKey`
Push operation has timed out	`Push Operation Timed Out`	A write operation times out.	`dataType`, `pushOperationGuid`
Account categories updated	`Account Categories Updated`	Anytime that Codat updates the `suggested` fields or a user updates the `confirmed` fields.	`modifiedDate`
Sync Connection Deleted	`Sync Connection Deleted`	A Sync for Commerce connection is deleted. Note: Sync for Commerce only.
Expenses sync completed	`Sync Completed`	An expense sync has completed. Note: Expenses only.	`syncId`, `syncType`
Expenses sync failed	`Sync Failed`	A failure occurred during an expense sync. Note: Expenses only.	`syncId`, `syncType`, `FailureStage`
Client rate limit exceeded	`Rate Limit Reached`	The number of requests to the API from a client has exceeded the current quota.	`dailyQuota`, `expiresUtc`
Client Rate Limit Reset	`Rate Limit Reset`	The client rate limit quota has reset and more requests are available.	`quotaRemaining`, `resetReason`, `dailyQuota`

Rules and payloads

Removing non-reference data from webhook body

In line with industry standard security practices, we have removed personally identifiable information, such as companyName, from the body of our webhooks. This leaves only referential information, such as companyId, which can be looked up using our API.

Company data connection status changed

Type: DataConnectionStatusChanged
Trigger: A data connection's status changes.
Additional data: dataConnectionId, platformKey, newStatus, oldStatus.

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002",
  "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "DataConnectionStatusChanged",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "Data connection for SandBox status changed from PendingAuth to Linked",
  "Data": {
    "dataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
    "newStatus": "Linked",
    "oldStatus": "PendingAuth",
    "platformKey": "gbol"
  }
}

New company synchronized

Type: New company synchronized
Trigger: Initial syncs are complete for all data types queued for a newly connected company, and at least one of those syncs is successful.

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002",
  "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "New company synchronized",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "Company 8a210b68-6988-11ed-a1eb-0242ac120002 synced for the first time",
  "Data": {
    "companyName": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
    "sourceType": "Accounting"
  }
}

Data sync completed

Type: Data sync completed
Trigger: Data synchronization is successfully completed in full for a specific data type.
Notification is sent for each dataType separately when the data type's individual sync is successfully complete.
Additional data: dataType, datasetId.

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002",
  "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "Data sync completed",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "Data sync of type creditNotes completed for company 7626befb-0c7d-49a4-9366-bc4c81b4e4b7",
  "Data": {
    "dataType": "creditNotes",
    "datasetId": "1541a5ee-0d84-4b6e-a7f7-c07c1f216333"
  }
}

Dataset data changed

Type: Dataset data changed
Trigger: A dataset synchronization has completed, which resulted in updates within Codat's data cache through the creation of new records or a change to existing records.
Notification is sent for each dataType separately when the data type's individual sync is successfully complete.
Additional data: dataType, datasetId.

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002",
  "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "Dataset data changed",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "Data has changed for dataset type invoices, company 8a210b68-6988-11ed-a1eb-0242ac120002",
  "Data": {
    "dataType": "invoices",
    "datasetId": "6586f21b-ad4d-4d06-a309-712af47184a2"
  }
}

Dataset status has changed to an error state

Type: Data Sync Status Changed To Error
Trigger: The synchronization of a dataset fails.
Additional data: dataType, datasetStatus, datasetId.

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002",
  "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "Data Sync Status Changed To Error",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "ERROR: syncing payments triggered a ProcessingError notification at 2020-04-21T12:12:57.4250446Z.",
  "Data": {
    "dataType": "invoices",
    "datasetStatus": "ProcessingError",
    "datasetId": "6586f21b-ad4d-4d06-a309-712af47184a2"
  }
}

Push operation status has changed

Type: Push Operation Status Changed()
Trigger: A write operation's status changes.
Additional data: dataType, status, pushOperationKey.

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002",
  "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "Push Operation Status Changed()",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "invoices triggered notification for PushOperationStatusChanged at 2019-05-22T18:19:42.742Z",
  "Data": {
    "dataType": "invoices",
    "status": "Success",
    "pushOperationKey": "c2f8847d-3047-4619-a157-6d947d8e4a73"
  }
}

Push operation has timed out

Type: Push Operation Timed Out
Trigger: A write operation times out.
Additional data: dataType, pushOperationGuid.

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002",
  "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "Push Operation Timed Out",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "ERROR: pushing invoices never finished in time, timing out at 2020-09-07T08:42:13",
  "Data": {
    "dataType": "invoices",
    "pushOperationKey": "c2f8847d-3047-4619-a157-6d947d8e4a73",
    "pushOperationGuid": "c2f8847d-3047-4619-a157-6d947d8e4a73"
  }
}

Account categories updated

Type: Account Categories Updated
Trigger: Any time that Codat updates the suggested fields or a user updates the confirmed fields.
Additional data: modifiedDate.

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002",
  "DataConnectionId": "2e9d2c44-f675-40ba-8049-353bfcb5e171",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "Account Categories Updated",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "Account categories updated for company f1c35bdc-1546-41b9-baf4-3f31135af968.",
  "Data": {
    "modifiedDate": "2019-08-24T14:15:22Z"
  }
}

Sync Connection Deleted

Type: Sync Connection Deleted
Trigger: A Sync for Commerce connection is deleted.
Note: This rule is specific to Sync for Commerce and cannot be used for other solutions.

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "CompanyId": "8a210b68-6988-11ed-a1eb-0242ac120002",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "Sync Connection Deleted",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "Sync connection for company 8a210b68-6988-11ed-a1eb-0242ac120002 deleted"
}

Expenses sync completed

Type: Sync Completed
Trigger: An expense sync has completed.
Additional data: syncId, syncType.
Note: This rule is specific to Expenses and cannot be used for other solutions.

{
  "ClientId": "30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e",
  "ClientName": "Expense Sync",
  "CompanyId": "1f9559e7-8368-48c9-bdf4-f158e16b8b85",
  "AlertId": "33a4f8e9-09ae-4334-9b00-7bbe83024672",
  "RuleId": "5c27631d-3b63-4b50-8228-ee502fd113eb",
  "RuleType": "Sync Completed",
  "Message": "Sync 321363b4-efa9-4fbc-b71c-0b58d62f3248 for company 1f9559e7-8368-48c9-bdf4-f158e16b8b85 of type Expense completed successfully.",
  "Data": {
    "syncId": "321363b4-efa9-4fbc-b71c-0b58d62f3248",
    "syncType": "Expense"
  }
}

Expenses sync failed

Type: Sync Failed
Trigger: A failure occurred during an expense sync.
Additional data: syncId, syncType, FailureStage.
Note: This rule is specific to Expenses and cannot be used for other solutions.

{
  "ClientId": "30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e",
  "ClientName": "Expense Sync",
  "CompanyId": "1f9559e7-8368-48c9-bdf4-f158e16b8b85",
  "RuleId": "289c80dc-2aee-4b71-afff-9acd8d051080",
  "RuleType": "Sync Failed",
  "AlertId": "72c1103b-7f17-4a3a-8db5-67c2d360a516",
  "Message": "Sync 3bead2a1-1b3d-4d90-8077-cddc5ca68b01 for company 1f9559e7-8368-48c9-bdf4-f158e16b8b85 of type Expense has failed at step Pushing.",
  "Data": {
    "syncId": "3bead2a1-1b3d-4d90-8077-cddc5ca68b01",
    "syncType": "Expense",
    "FailureStage": "Pushing"
  }
}

Client rate limit reached

Type: Rate Limit Reached
Trigger: The number of requests to the API from this client has exceeded the current quota. Rate limits apply to a client as a whole, so this rule cannot be filtered by company and does not include a companyId.
Additional data: dailyQuota, expiresUtc

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "Rate Limit Reached",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "The current daily rate limit quota of 1000 requests for bae71d36-ff47-420a-b4a6-f8c9ddf41140 has been reached.",
  "Data": {
    "DailyQuota": 1000,
    "ExpiresUtc": "2023-05-03T00:00:00Z"
  }
}

Client rate limit reset

Type: Rate Limit Reset
Trigger: The rate limit quota has reset and more requests are available. Rate limits apply to a client as a whole, so this rule cannot be filtered by company and does not include a companyId.
Additional data: quotaRemaining, resetReason, dailyQuota

{
  "ClientId": "bae71d36-ff47-420a-b4a6-f8c9ddf41140",
  "ClientName": "Bank of Dave",
  "RuleId": "70af3071-65d9-4ec3-b3cb-5283e8d55dac",
  "RuleType": "Rate Limit Reset",
  "AlertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  "Message": "The current daily rate limit quota for client 30e0f9d2-52c0-4c9f-a806-bcd98a3bcd7e has been reset to 1000 requests.",
  "Data": {
    "QuotaRemaining": 1000,
    "ResetReason": "The quota was reset because it is a new day.",
    "DailyQuota": 1000,
    "ExpiresUtc": "2023-05-03T00:00:00Z"
  }
}

Was this page useful?

👏

👍

🤔

👎

😭

Rules and payloads​

New companyCompany In Codat, a company represents your customer's business entity. Companies can have multiple connections to different data sources. synchronized​

Data syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. completed​

Dataset data changed​

Dataset status has changed to an error state​

Push operation status has changed​

Push operation has timed out​

Account categories updated​

Expenses syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. completed​

Expenses syncSync The process of fetching the latest data from a connected data source. Syncs can be triggered manually or run automatically on a schedule. failed​

Client rate limit reached​

Client rate limit reset​

Contents