What FreshBooks events are synced to Databricks?

ml-connector supports all FreshBooks entity events: invoice.create, invoice.update, payment.create, payment.update, bill.create, bill.update, expense.create, expense.update, bill_vendor.create, bill_vendor.update, client.create, and client.update, among others. Each event is transformed into a Databricks table row with the object_id, account_id, identity_id, event_type, and timestamp fields so you can query the full history of changes.

How does ml-connector handle FreshBooks' webhook timeout and retry behavior?

FreshBooks webhooks have a 10-second timeout; if ml-connector does not return a 2xx response in time, FreshBooks will retry. ml-connector returns 202 immediately after validating the signature and queuing the payload for insert, so the FreshBooks timeout is avoided. If the Databricks insert fails, ml-connector logs the event and flags it for manual replay via the audit trail.

Do I need to create Databricks delta tables ahead of time?

No. ml-connector inspects the target schema at startup and creates any missing tables using Unity Catalog conventions (column names, data types, and Delta settings from the FreshBooks event schema). If a new FreshBooks event type is added later, ml-connector validates the table exists or creates it on first insert.

FreshBooksDatabricks

FreshBooks and Databricks integration

FreshBooks is where your accounting data lives: invoices, expenses, bills, payments, and journal entries. Databricks is where you analyze and govern that data across your organization. Connecting them puts your accounting records into a unified, searchable data warehouse, so finance teams can build dashboards, run reconciliation queries, and feed downstream analytics pipelines without pulling data by hand. ml-connector handles the FreshBooks OAuth flow and the Databricks table schema validation on your behalf.

How FreshBooks works

FreshBooks exposes clients, invoices, bills, payments, expenses, items, chart of accounts, and journal entries through REST APIs partitioned into accounting and time-tracking namespaces. All requests authenticate with OAuth 2.0 user-delegated tokens (not Client Credentials) against https://api.freshbooks.com. FreshBooks publishes real-time events via webhooks: invoice.create, invoice.update, payment.create, payment.update, bill.create, bill.update, and expense.create among others. Webhook payloads arrive as application/x-www-form-urlencoded with HMAC-SHA256 signatures. Webhook delivery can range from seconds to several minutes, and timeout after 10 seconds triggers retries.

How Databricks works

Databricks exposes compute resources, SQL warehouses, catalogs, schemas, and delta tables through workspace-scoped REST APIs at /api/2.0/ and /api/2.1/ endpoints. Authentication uses OAuth 2.0 Client Credentials with a Service Principal (client_id and client_secret); bearer tokens expire after 3600 seconds. Data writes into Databricks tables can be metadata operations via REST or full data writes via SQL and Spark. Databricks is a data platform without native finance objects, so all FreshBooks GL entities (invoices, payments, vendors, accounts) are modeled as custom Databricks delta tables in a user-defined schema.

What moves between them

FreshBooks events (invoices, payments, bills, expenses, clients) flow into Databricks. ml-connector listens on a customer-supplied webhook endpoint, receives the signed FreshBooks payload, validates the HMAC-SHA256 signature, and maps each event into a Databricks delta table row. Direction is FreshBooks to Databricks only; Databricks does not push data back into FreshBooks. Sync cadence is real-time at webhook delivery (seconds to minutes). Reference data such as chart of accounts and clients is also written to Databricks tables, so downstream queries can join invoices to accounts and expenses to cost allocation dimensions.

How ml-connector handles it

ml-connector stores both the FreshBooks OAuth credentials and the Databricks Service Principal secret encrypted at rest. On webhook delivery, it validates the X-FreshBooks-Hmac-SHA256 signature using the customer's webhook signing key, parses the event payload, and constructs a Databricks-compatible row (object_id, account_id, identity_id, event_type, timestamp, and data fields). Before writing, it acquires a fresh Databricks bearer token and checks the target table schema; if the table does not exist, ml-connector creates it in the customer-configured schema using Unity Catalog conventions. Failed inserts are retried with exponential backoff. Webhook timeouts (FreshBooks' 10-second limit) are handled on FreshBooks' side; ml-connector logs every insert and maintains a full audit trail so any payload can be replayed if a downstream query or data governance audit requires it.

A real-world example

A growing software-as-a-service company with 50 employees uses FreshBooks for invoicing and expense tracking. The finance team needs to build monthly dashboards of revenue by customer, track headcount-to-payroll spending ratios, and reconcile FreshBooks invoices against customer payment records in their data warehouse. Before the integration, they exported FreshBooks CSV reports monthly and loaded them into Databricks by hand. With FreshBooks and Databricks connected, each invoice, payment, and expense appears in Databricks tables within minutes of creation. The finance team runs SQL queries to forecast revenue, identify late-paying customers, and track expense trends by category without re-keying any data.

What you can do

Stream FreshBooks invoices, payments, bills, and expenses into Databricks delta tables in real-time via webhooks.
Validate HMAC-SHA256 webhook signatures and map FreshBooks events to Databricks-compatible row schemas.
Manage OAuth 2.0 token refresh for both FreshBooks and Databricks Service Principal credentials.
Create and validate Databricks target tables using Unity Catalog conventions if they do not exist.
Replay any failed webhook payload or query the full audit trail to debug data discrepancies.

Questions

What FreshBooks events are synced to Databricks?: ml-connector supports all FreshBooks entity events: invoice.create, invoice.update, payment.create, payment.update, bill.create, bill.update, expense.create, expense.update, bill_vendor.create, bill_vendor.update, client.create, and client.update, among others. Each event is transformed into a Databricks table row with the object_id, account_id, identity_id, event_type, and timestamp fields so you can query the full history of changes.
How does ml-connector handle FreshBooks' webhook timeout and retry behavior?: FreshBooks webhooks have a 10-second timeout; if ml-connector does not return a 2xx response in time, FreshBooks will retry. ml-connector returns 202 immediately after validating the signature and queuing the payload for insert, so the FreshBooks timeout is avoided. If the Databricks insert fails, ml-connector logs the event and flags it for manual replay via the audit trail.
Do I need to create Databricks delta tables ahead of time?: No. ml-connector inspects the target schema at startup and creates any missing tables using Unity Catalog conventions (column names, data types, and Delta settings from the FreshBooks event schema). If a new FreshBooks event type is added later, ml-connector validates the table exists or creates it on first insert.

Connect FreshBooks and Databricks

Free to use. Add your credentials, ping your real systems, and see if we fit.

Get started