FreshBooks and Salesforce integration

What moves between them

The main flow runs from FreshBooks to Salesforce. When a client is created in FreshBooks, ml-connector creates a matching Account in Salesforce. Invoices become Opportunities with the invoice amount and due date carried forward. When a payment is received in FreshBooks, the matching Salesforce Opportunity is marked closed-won and linked to the Salesforce Invoice if the org has Order Management. The reverse (Salesforce contacts pushing back to FreshBooks) is read-only: ml-connector reads Accounts and Orders from Salesforce for enrichment and reporting but does not modify them. Syncs happen in near real-time via FreshBooks webhooks, so new invoice activity appears in Salesforce within minutes.

How ml-connector handles it

ml-connector stores the FreshBooks OAuth user credential (which expires and must be refreshed periodically) and the Salesforce client credentials separately. On FreshBooks events, it validates the webhook signature using HMAC-SHA256 and the customer's webhook secret, then converts the FreshBooks record (e.g., invoice with client reference, amount, and due date) into a Salesforce object (Opportunity, Account, or related record). The mapping is deterministic: FreshBooks client ID maps to a Salesforce Account lookup, invoice ID maps to Opportunity ID. Because Salesforce client credentials flow does not support refresh tokens, ml-connector refreshes the bearer token on 401 response and uses My Domain URL to avoid auth endpoint conflicts. FreshBooks webhooks can delay from seconds to several minutes, so ml-connector idempotently upserts records and carries full audit trails on every sync. If a Salesforce write fails (e.g., Account not found), the audit log captures the error and can replay the record when the lookup is available.

A real-world example

A mid-sized professional services firm uses FreshBooks for accounting and invoicing, and Salesforce for sales and project tracking. Before the integration, the finance team received payments in FreshBooks, manually looked up the corresponding opportunity in Salesforce, and marked it closed-won, then exported invoice details once a month for reconciliation. Now, when a payment arrives in FreshBooks, the Salesforce Opportunity closes automatically, the invoice amount syncs to the Order for billing-cost tracking, and the finance team can see the sales pipeline in FreshBooks' accounts for better cash-flow forecasting. Salesforce users see payment status and invoice numbers directly on the Account, eliminating the need to cross-reference two systems.

What you can do

• •Sync FreshBooks clients into Salesforce Accounts with company name, email, and contact details.
• •Create Salesforce Opportunities from FreshBooks invoices with amount, due date, and client linkage.
• •Mark Salesforce Opportunities closed-won when payment is received in FreshBooks.
• •Handle FreshBooks OAuth user-delegated tokens and Salesforce client credentials across different auth schemes.
• •Receive FreshBooks webhook events in near real-time and validate signatures with HMAC-SHA256 before syncing.

Questions

Which direction does data flow between FreshBooks and Salesforce?

The primary flow is FreshBooks to Salesforce. Clients, invoices, and payments from FreshBooks sync into Salesforce Accounts, Opportunities, and Invoice records. The reverse direction is read-only: ml-connector reads Salesforce Accounts and Orders for enrichment and reporting but does not write them back to FreshBooks. This asymmetry reflects FreshBooks' role as the source of truth for financial records.

Does FreshBooks webhook delay affect real-time visibility in Salesforce?

FreshBooks webhooks can deliver within seconds to several minutes depending on FreshBooks' infrastructure. ml-connector receives and processes each webhook immediately, so Salesforce records update as soon as FreshBooks delivers the event. If webhook delivery is delayed, the Salesforce record will be delayed by the same amount. For time-critical syncs, ml-connector can also poll FreshBooks invoices and payments on a schedule you define.

How does ml-connector handle the different OAuth flows between FreshBooks and Salesforce?

FreshBooks uses user-delegated OAuth 2.0 (tokens tied to a specific user and scopes), while Salesforce uses client credentials (server-to-server). ml-connector stores both credential types encrypted and refreshes each independently. FreshBooks tokens expire after a user-configured period and are refreshed on demand; Salesforce client credentials are refreshed on 401 response and do not use refresh tokens, so ml-connector always re-authenticates with the consumer key and secret.