FreshBooks and Microsoft Teams integration

What moves between them

FreshBooks invoices, bills, and payments flow into Microsoft Teams channels in near real-time via FreshBooks webhooks. When an invoice is created, updated, or deleted in FreshBooks, ml-connector formats the event and sends a message to a pre-configured Teams channel. Bill and payment events follow the same pattern. The flow is read-only from Teams perspective: Teams receives notifications but does not write back into FreshBooks.

How ml-connector handles it

ml-connector stores FreshBooks user OAuth tokens encrypted and refreshes them before expiry. On the Teams side, it authenticates as a daemon app using Entra ID Client Credentials, obtaining an access token to call the Microsoft Graph API. FreshBooks webhooks are validated by comparing the HMAC-SHA256 signature in the X-FreshBooks-Hmac-SHA256 header against the payload. Microsoft Graph change notifications are validated by matching the clientState field in the subscription. Because FreshBooks webhooks can be slow (seconds to minutes) and Microsoft Graph subscriptions expire in 3 days, ml-connector tracks subscription expiry and renews before the deadline to avoid losing notifications. Each webhook event is logged with a full audit trail, including the raw event, the formatted Teams message, and the Graph response, so failed sends can be retried.

A real-world example

A small-to-mid-sized professional services firm runs FreshBooks for accounting and uses Microsoft Teams for team collaboration. The finance manager currently checks FreshBooks every morning to see new invoices and bills, then manually posts status updates to the finance channel so that project managers and executives know what is pending. When an invoice goes unpaid beyond terms or a vendor bill arrives, important deadlines slip because the notification is buried in chat or missed entirely. By connecting FreshBooks and Teams, invoice and bill events post automatically to the finance channel in a structured format. The team sees new invoices within minutes of creation, project managers are notified of bills related to their projects, and payment due dates are visible in the channel history. The manual morning check becomes unnecessary, and critical dates are harder to miss.

What you can do

• •Push FreshBooks invoice, bill, and payment events to Microsoft Teams channels as formatted messages.
• •Validate FreshBooks HMAC-SHA256 webhook signatures and Teams clientState subscription metadata.
• •Authenticate with FreshBooks user-delegated OAuth tokens and refresh them automatically.
• •Use Microsoft Entra ID Client Credentials to access Microsoft Graph as a daemon app.
• •Track Microsoft Graph subscription expiry and renew subscriptions before they expire to avoid losing notifications.

Questions

Does the integration write data back from Teams into FreshBooks?

No. The integration is unidirectional: FreshBooks events are sent to Teams as notifications. Teams does not write back to FreshBooks. The flow delivers accounting updates to your team communication channel, not a full bidirectional sync.

How does ml-connector handle the difference in how FreshBooks and Teams validate webhooks?

FreshBooks uses HMAC-SHA256 signatures via the X-FreshBooks-Hmac-SHA256 header. Microsoft Graph uses clientState matching and validationToken handshakes. ml-connector validates each system's signature method independently: it compares the FreshBooks HMAC to the payload, and it matches the Microsoft Graph clientState to the subscription record to confirm the notification is authentic.

Why do Microsoft Graph subscriptions need renewal, and how does ml-connector handle it?

Microsoft Graph subscriptions expire in 3 days by default (shorter for presence and shifts). If a subscription expires, ml-connector will stop receiving notifications. ml-connector tracks subscription creation and expiry time, renews the subscription at least one day before expiry, and logs each renewal so you can monitor the subscription lifecycle.