Skip to main content

​
The pieces

Organization. Your company’s account, shared with your teammates. Its owners get the alerts: a webhook that couldn’t be delivered, a connection whose requests have waited a week. App. Your product’s identity in QuBe Sync, with its own API key, webhook secrets, connections and workflows. A sandbox app is for building and testing. A production app holds your customers’ connections. You start with one of each, and nothing crosses between them: a sandbox key can’t reach a production connection. Connection. One QuickBooks company file, usually one per customer. It carries the Web Connector’s credentials and knows when it last checked in (last_connected_at). It is standard (the Web Connector checks in every 5 minutes), realtime (every 10 seconds) or simulated (a fake QuickBooks hosted by QuBe Sync, for development). A realtime or simulated connection can also run workflows and match names against an index of its company file’s lists, and its name_index says where that index stands. Queued request. One QuickBooks operation, such as listing customers or adding an invoice, queued against a connection. You queue it with JSON, and its answer is delivered to your webhook_url. Workflow run. A multi-step job QuBe Sync runs for you: several requests, the logic between them, and questions for your app when the chart calls for one. See Workflows.

​
Why every request is asynchronous

QuickBooks Desktop runs on your customer’s Windows machine, behind their firewall. Nothing on the internet can call it. Intuit’s Web Connector, installed alongside QuickBooks, calls out instead: on a schedule it asks QuBe Sync whether there is work, runs it in QuickBooks, and hands back the answers. So an API call to QuBe Sync can’t return QuickBooks data. It returns a queued request, and the data follows by webhook once the Web Connector has asked for work:
Queue from anywhere, act on the webhookDo the follow-up work, like storing the new customer’s list_id, in your webhook handler.
One request at a time, in orderA connection’s requests go to QuickBooks in the order you queued them, even when a Web Connector session ends part way: what was queued later waits. If one request depends on the answer to another, queue it from the first request’s webhook. Better yet, let a workflow do the sequencing.
Built-in fault-toleranceWe can’t control whether QuickBooks is open on your customer’s computer, or ready to process requests, but we can gracefully handle every situation. When QuickBooks throws a connection error, show users the user_message so they can solve problems themselves without contacting support. The request is automatically retried once the Web Connector resumes functioning.
Do you need realtime integration?A standard connection polls every five minutes. When a person is waiting on results, use realtime connections that start processing requests within 10 seconds. Workflows run only on realtime connections.

​
The life of a request

The last four are final. Error handling covers what to do with each.

​
Speed and scheduling

Choose standard or realtime with type when you create the connection. Update Selected in the Web Connector runs a sync immediately, whatever the schedule.
“Update postponed by application” is normal. Every connection’s Web Connector is set to run every 10 seconds, and QuBe Sync tells it to wait when it isn’t due. That’s how a standard connection picks up requests every 5 minutes, and why its Last Result often reads “Update postponed by application”. It checks in again on its own. The schedule column (Every Min) is blank for a QuBe Sync entry, which is expected. Leave Auto-Run ticked and don’t edit the schedule in the Web Connector: QuBe Sync controls it.
You can switch a connection between standard and realtime from its page in the dashboard: To see when a connection will next pick up requests, read it on the connection (GET /connections/{connection_id} in v2), or the Speed card on its dashboard page:
​
string | null
When the connection will next pick up requests. A time more than a minute in the past means the check-in is late: a long session is still running, or the Web Connector isn’t running on the QuickBooks computer.
​
boolean
true while QuBe Sync is spacing the tries out because QuickBooks can’t be reached.
Realtime connections in a sandbox app slow down while idle. After 10 minutes without a request, they check in once a minute; after an hour, every 5 minutes. The session that picks up the next request brings them back to every 10 seconds. To run a request immediately, click Update Selected (a click within about 20 seconds of a scheduled run is treated as the schedule and postponed; click again). The connection’s page says when this is why its next check-in is minutes away, and so does next_check_in_reason (sandbox_idle) on the connection.

​
Security

Each App has its own API keys and webhook secretsThey reach that app’s connections, requests and workflows, and nothing else. Keys start with sk_, and you can create or expire them in the dashboard.
Webhooks are signedEach is signed with your app’s webhook secret (HMAC-SHA256 over a timestamp and the body), so you can reject anything that didn’t come from QuBe Sync. Verify signatures.
Sandbox and production are separate appsThey have separate keys, secrets and connections.
QuBe Sync never needs your customer’s QuickBooks loginThe Web Connector authenticates to QuBe Sync with a per-connection username and password, and QuickBooks itself is only ever reached from their PC.
RetentionAn answered request is kept for 60 days, then deleted, and one that failed (error, timed_out or discarded) for 90. Workflow runs, and the requests they sent, age out after 60 days. These can also be deleted immediately upon receipt by your app via the API.