FreshBooks and IBM Sterling integration

What moves between them

FreshBooks invoices, bills, and payments flow into IBM Sterling via webhook events. ml-connector receives FreshBooks webhook notifications, transforms the accounting records into EDI documents (ANSI X12 810 for invoices, 820 for payments), and routes them into Sterling mailbox workflows for translation and delivery to trading partners. Reference data such as FreshBooks bill vendors and chart of accounts are mapped to IBM Sterling trading partners and GL segments. IBM Sterling acknowledgements and delivery status are polled on a schedule and can be logged back to FreshBooks via custom audit entries.

How ml-connector handles it

ml-connector receives FreshBooks webhook POST events, verifies the HMAC-SHA256 signature using the stored webhook secret, and decrypts the stored FreshBooks OAuth 2.0 credentials to validate permissions. When a FreshBooks OAuth token expires (detected via 401 response), ml-connector refreshes it using the refresh token and stored client credentials. For each qualifying invoice, bill, or payment event, ml-connector constructs the corresponding EDI document (850 for POs if available, 810 for invoices, 820 for payments), maps the FreshBooks chart of accounts and vendor details to IBM Sterling trading partner and GL dimensions, and posts the document into the target Sterling mailbox via the B2BAPIs REST endpoint. Because IBM Sterling REST API does not expose outbound webhooks, ml-connector polls the mailbox message queue on a regular schedule to detect acknowledgements and delivery status changes. FreshBooks webhook payloads include only the object_id and account_id, so ml-connector fetches the full record via FreshBooks REST for context. Webhook delivery can range from seconds to several minutes, and failed webhooks disable the callback after persistent failures, so ml-connector also supports on-demand replay via audit trails.

A real-world example

A mid-sized B2B distributor uses FreshBooks for accounting and invoicing, and IBM Sterling B2B Integrator to manage EDI transactions with major suppliers and customers. Before the integration, the finance team exported FreshBooks invoices at month-end and manually created EDI 810 documents in Sterling for each customer, then waited for acknowledgements and manually logged them back into FreshBooks for reconciliation. With FreshBooks and IBM Sterling connected, each FreshBooks invoice automatically routes into Sterling as an EDI document with the correct trading partner and GL segments, and acknowledgements are polled and logged back to FreshBooks on a defined schedule. Month-end invoice submission is now automatic, and reconciliation is driven by the audit trail.

What you can do

• •Route FreshBooks invoices into IBM Sterling as ANSI X12 810 EDI documents with automatic chart of accounts and vendor-to-trading-partner mapping.
• •Convert FreshBooks bill payments into EDI 820 remittance documents for supplier reconciliation in Sterling workflows.
• •Verify FreshBooks webhook signatures (HMAC-SHA256) and refresh expired OAuth 2.0 tokens transparently.
• •Poll IBM Sterling mailbox messages to detect EDI acknowledgements and delivery status, with audit logging and replay support.
• •Map FreshBooks bill vendors to IBM Sterling trading partners and synchronize chart of accounts GL segments across both systems.

Questions

Does FreshBooks support Client Credentials OAuth or only user-delegated authorization?

FreshBooks supports user-delegated OAuth 2.0 Authorization Code grant only. ml-connector stores the refresh token encrypted and exchanges it for a new access token when the current token expires. There is no shared public FreshBooks token endpoint, so ml-connector refreshes tokens by making a request back to the FreshBooks token endpoint on behalf of the authenticated user.

How does ml-connector handle the fact that IBM Sterling is on-premises or customer-managed cloud, not a shared SaaS?

ml-connector requires the customer to provide the full IBM Sterling instance URL (https://<b2bi-host>:<port>) and the HTTP Basic Auth credentials (or OAuth 2.0 client credentials for Sterling v6.2.2+). Each customer instance has its own token endpoint and mailbox namespace, so ml-connector stores these per-customer and routes requests to the correct instance. Network access (VPN or DMZ) to the customer's B2Bi instance is a prerequisite.

Why does ml-connector poll IBM Sterling mailbox messages instead of waiting for a push from Sterling?

IBM Sterling REST API does not support outbound webhooks. ml-connector polls the /B2BAPIs/svc/mailboxMessages/ endpoint on a schedule (recommended every 1-5 minutes) to detect new documents and acknowledgements. FreshBooks, by contrast, pushes webhook events in real-time, so ml-connector receives inbound invoices and payments immediately but must actively check Sterling for responses and delivery status.