QuickBooks Online webhooks: Maesn turns the CloudEvents envelope into one event body

QuickBooks Online publishes webhooks for 29 entity types, and it does not publish the same operations for all of them. The table in Intuit’s configuration guide has six columns, and each entity ticks only the ones that apply to it.

Update is the only operation that reaches every documented entity. Create reaches all of them except Preferences, which can be changed but not created. Delete stops at the transactions and name lists that can be removed at all.

The remaining three are narrower by nature rather than by policy. Merge exists on name-list entities such as Customer, Vendor and Item. Void exists on transactions that can be voided instead of deleted. Emailed exists on documents you send to someone.

Which of those you actually receive is a separate question from which exist, because you select the events per app in the developer dashboard. The full matrix of what a connected company can send lives on the QuickBooks API page, alongside the objects the unified model exposes.

A notification arrives as a JSON array of CloudEvents envelopes. Each envelope describes one change: the specification version, an event id, the source, an event type, a timestamp, the entity id in intuitentityid and the company in intuitaccountid.

The event type carries the entity and the operation in one string, in the form qbo.customer.merged.v1 or qbo.salesreceipt.updated.v1. That string is where your routing decision comes from, rather than a nested entities array.

What no envelope contains is the record itself. You learn that customer 123 was merged, not what the surviving customer now looks like, so every event that matters becomes an event plus a read. That second call is the subject of how to integrate with QuickBooks.

Your endpoint has to return HTTP 200 within three seconds. That window is measured on the acknowledgement rather than on your processing, which is why Intuit asks you to queue the payload and do the work on another thread.

Miss it, and the event is retried on a fixed sequence: 10 seconds, 20, 30, then 5 minutes, 20 minutes, 2 hours, 4 hours, 6 hours, and every 6 hours from there. The ladder is generous at the top and slow at the bottom.

The part that decides an architecture is what happens meanwhile. Intuit states that you may not receive subsequent events until the first one is acknowledged correctly, so a handler that is slow on one event is not slow on one event. It is stalled on the queue behind it.

Ordering is not guaranteed either. Events can arrive out of sequence, and Intuit names the timestamp in the payload as the source of truth for when a change actually happened. A handler that trusts arrival order will apply an older change over a newer one.

Intuit does not present webhooks as a complete record, and the clearest evidence is its own first best practice. To compensate for the possibility of missed events, it asks you to make a change data capture call for every entity you care about.

The call is a polling operation. You name the entities and a look-back date, and the response carries the full payload of everything that changed since then, with deleted records marked by a status field rather than omitted.

Two documented limits decide how much of a safety net that is. Changes are tracked for 30 days, so an outage longer than that is outside what the call can recover. And a response returns at most 1.000 objects, which is why Intuit suggests querying shorter periods.

So a QuickBooks integration that wants to be correct runs two mechanisms rather than one: a listener for the events, and a poller that goes back over the same ground to find what the listener did not get. Both have to be built, monitored and reasoned about together.

Through the unified endpoint you subscribe once and handle one event body. The envelope QuickBooks publishes is parsed on our side, and what reaches your handler is the same structure you already receive from every other connected system.

That is two normalisations rather than one, and both are the kind you would otherwise write per vendor. The payload becomes one shape instead of a per-vendor envelope whose optional blocks you have to learn. The signature becomes one check instead of a different scheme for each system.

QuickBooks Online uses the app-based delivery model, where every connected company arrives at a single endpoint and each payload names its company. Systems built the other way subscribe per customer instead. Handling both of those models in one codebase is the work the unified endpoint removes.

Two things stay with you, and both are worth planning for. Deciding what a change means for your product is yours, and so is idempotency: networks retry, so key the work on the resource id and the event type rather than assuming each event arrives once.

What we do not do is run Intuit’s change data capture backfill on your behalf. Maesn polls the systems that publish nothing, and QuickBooks publishes. The recovery call in the section above stays a decision you make about your own tolerance for a missed event.