Imagine an accounting dashboard that shows a customer's outstanding invoices. If the customer marks an invoice as paid in QuickBooks Online, they expect your product to reflect it without pressing a refresh button.
QuickBooks Online webhooks make that possible. Intuit notifies your application when supported entities change in a connected company, and your application retrieves the updated data through the QuickBooks Online Accounting API.
This guide covers how QuickBooks webhooks fit into a SaaS integration, what you need to configure, and how to process notifications safely. Intuit updates its developer platform periodically, so confirm field names, payload formats and limits in Intuit's current documentation before you build.
QuickBooks webhooks are configured on your app in the Intuit Developer portal, not per customer. Once configured, notifications cover the QuickBooks companies that have authorized your app through OAuth 2.0.
The flow looks like this:
A customer connects their QuickBooks Online company to your product using OAuth.
Something changes in that company, for example an invoice is updated.
Intuit sends an HTTP POST to your webhook endpoint describing which entities changed.
Your receiver verifies the request and acknowledges it.
A background worker calls the Accounting API, using that company's authorization, to fetch the current version of each changed entity.
Your application updates its own records.
The notification tells you *what* changed. The API tells you *what it looks like now*.
A QuickBooks notification is a signal to fetch fresh data, processed in the background after a fast acknowledgement.
A QuickBooks Online app in the Intuit Developer portal, with OAuth 2.0 configured for the Accounting scope.
A public HTTPS endpoint that Intuit can reach. Intuit's sandbox environment is useful for testing.
A webhook verifier token, issued in the developer portal when you set up webhooks. You'll use it to validate signatures.
A mapping of company IDs to customers. QuickBooks identifies each connected company with a realm ID. Store it when the customer connects so incoming notifications can be routed to the right tenant.
In the developer portal, open your app's webhook settings, enter your endpoint URL and select the entities you want to receive notifications for, such as invoices, payments or customers. Development and production keys are configured separately, so repeat the setup for each environment.
Subscribe only to entities your product actually uses. Every extra entity means more notifications to verify, process and ignore.
Intuit signs each notification. The signature is sent in a request header and is computed with HMAC-SHA256 over the raw request body using your verifier token.
To verify:
Read the raw body exactly as received, before any JSON parsing.
Compute an HMAC-SHA256 of that body using your verifier token.
Compare the result with the signature header using a constant-time comparison.
Reject the request if they don't match.
Never skip verification in production, even temporarily. Your endpoint is publicly reachable.
Return a successful response as soon as the request is verified and stored. Fetching entities and updating your database should happen in a queue-backed worker. Slow responses can be treated as failed deliveries.
A single notification can include changes for more than one company and more than one entity. Split it by realm ID, look up the matching connection, and process each company with its own credentials.
Use the entity type and ID from the notification to read the latest version through the Accounting API. This protects you from out-of-order delivery and from acting on stale data.
Notifications can describe operations other than create and update, such as delete or merge. Decide what your product should do in each case. A deleted invoice might need to be hidden, archived or flagged rather than silently removed.
Webhooks can be missed: your endpoint might be unavailable during a deployment, or a notification might fail repeatedly. QuickBooks Online offers a change data capture (CDC) operation that returns entities changed since a given time. Running it on a schedule, per company, lets you reconcile anything a notification didn't deliver.
A practical pattern is to store, per company, the timestamp of the last successful reconciliation and use it as the starting point for the next CDC call.
Signature verification fails. Usually the body was modified before hashing, the wrong environment's verifier token was used, or the comparison didn't use the raw bytes.
Notifications arrive for unknown companies. A customer may have disconnected in your product while the app is still authorized in QuickBooks. Log and ignore unknown realm IDs, and clean up authorizations when customers disconnect.
API calls fail after a notification. The company's access token may have expired or the authorization may have been revoked. Refresh the token, and if refresh fails, mark the connection as needing reauthorization and tell the customer.
Duplicate records in your database. Upsert by QuickBooks entity ID rather than inserting on every notification.
Every notification leads to an API call for a specific QuickBooks company, which requires a valid, current authorization for that company. Managing those authorizations across many customers is separate work from processing the events.
Pathfix OAuth handles the OAuth flow, token storage, refresh and authenticated API passthrough, and QuickBooks is among its supported providers. Your application still owns the webhook receiver, the API requests and how invoice data appears in your product.
If you'd rather configure the event handling as a workflow, Pathfix Automation can run API workflows in each connected user's context, including user-level webhook listening for supported providers.
No. QuickBooks webhooks are configured once per app and environment. Notifications identify the company they relate to, and your application routes them.
