FreshBooks and Microsoft Dynamics 365 Sales integration

What moves between them

Invoices and payments flow from FreshBooks into Dynamics 365 Sales. When a FreshBooks invoice is created or updated, ml-connector receives the webhook, transforms the invoice into an Dynamics 365 Sales account activity or linked record, and writes it via OData. Payment records flow the same way, appended to the associated invoice activity. Clients in FreshBooks can be mapped to accounts in Dynamics 365 Sales so invoice records land on the correct customer. Journal entries from FreshBooks do not sync to Sales, since Sales has no GL capability.

How ml-connector handles it

ml-connector stores the FreshBooks OAuth refresh token encrypted and exchanges it for a fresh bearer token before each call, using the full user-delegated flow to access the FreshBooks namespaces for the correct account and business ID. For Dynamics 365 Sales, ml-connector presents client credentials once per session, caches the Entra token, and refreshes it when it nears expiry. FreshBooks webhooks arrive with HMAC-SHA256 signatures validated against the registered webhook secret. When a webhook delivery times out or fails with a non-2xx code, ml-connector queues a retry; if FreshBooks marks the callback as persistently failed, ml-connector polls the FreshBooks API on a fallback cadence to detect missed events. Client and invoice records are matched by exact name or a custom mapping field, so the same client name in both systems routes invoice data to the correct account in Sales. Dataverse webhook payloads are capped at 256 KB, so large FreshBooks invoices with many line items are split across multiple writes if needed.

A real-world example

A mid-market consulting firm uses FreshBooks for time tracking and invoicing, and Dynamics 365 Sales for pipeline management. Before the integration, the sales team saw only pipeline deals in Sales and had to ask finance for invoice status on every customer call. The finance team manually logged payment notes into Sales to keep the conversation history complete. With FreshBooks and Dynamics 365 Sales connected, every invoice is automatically linked to the associated account in Sales, showing payment status and due dates on the opportunity timeline. Payment receipts appear as activities so the sales team always knows the financial position of each deal, and month-end reconciliation no longer requires manual cross-referencing.

What you can do

• •Push invoices from FreshBooks into Dynamics 365 Sales as linked records on the matching account, showing invoice date, amount, and due date.
• •Sync payment records from FreshBooks into Sales as activities so sales teams see payment status on every deal.
• •Map FreshBooks clients to Dynamics 365 Sales accounts by name or custom field so invoices land on the correct customer.
• •Validate webhook signatures from FreshBooks using HMAC-SHA256 and queue retries on delivery failures.
• •Exchange FreshBooks refresh tokens for fresh bearer tokens and manage Entra ID client credentials with automatic expiry handling.

Questions

Does FreshBooks support client credentials OAuth, or does every FreshBooks user need to log in separately?

FreshBooks only supports OAuth 2.0 Authorization Code grant with user delegation, not client credentials. ml-connector stores the refresh token encrypted after the first user logs in once, then exchanges it for fresh bearer tokens automatically. This means one FreshBooks user grants access, and ml-connector can then sync data across all invoices and payments in that FreshBooks account without requiring additional logins.

What happens if a FreshBooks webhook delivery fails or times out?

FreshBooks webhooks have a 10-second timeout, and non-2xx responses or timeouts trigger retries. If failures persist, FreshBooks disables the webhook callback. ml-connector detects this and falls back to polling the FreshBooks API at regular intervals to catch any missed events. This ensures no invoice or payment is lost even if webhook delivery is temporarily unavailable.

How are clients in FreshBooks matched to accounts in Dynamics 365 Sales?

Clients are matched by exact name by default, so a client named 'Acme Corp' in FreshBooks routes to the account 'Acme Corp' in Dynamics 365 Sales. You can also configure a custom field mapping if your naming conventions differ between systems. If no match is found, ml-connector logs the mismatch and can either create a new account in Sales or hold the record for manual review, depending on your configuration.