Integrations, APIs, and Sync Hub

An integration is a promise between systems. It says which system owns which record, what fields move, when they move, what happens on failure, and how people know the sync is healthy.

Weak integrations fail quietly. Strong integrations are narrow, monitored, retryable, and explainable.

In practice, write the contract down for each connection AWRA tracks: QuickBooks Online, outbound webhooks, payment providers and the Developer API. Settings → Integration Sync Hub shows each one as healthy, warning or failing, with its failures, retries, dead letters, mapping errors and last success, beside a named owner and a runbook note you assign. For QuickBooks the contract is one-way by design: AWRA pushes suppliers, items, purchase orders, customers, issued invoices, payments received and tax codes, while journals, supplier bills and credit notes stay in AWRA. The hub also shows the data problems that will make a sync fail before it runs, such as a missing tax code, an unmapped account, a duplicate item name, an unsupported currency or an expired connection token, so the contract is checked before it is broken.

API keys should be treated like operational access, not just developer convenience. Create them deliberately, rotate them, revoke them when no longer needed, and avoid broad keys for narrow jobs.

Webhooks are similar: they are useful because they push events quickly, but they need signing, testing, throttling, retry logs, and clear ownership when delivery fails.

In practice, a team wants a script that reads stock levels and creates draft invoices. Create a key at Settings → API Keys with only what that job needs: a read key never writes, and creating draft invoices needs the sales:write scope by name rather than the developer:write umbrella. Keep the key in server-side configuration, never in a browser page or a mobile app, and send an Idempotency-Key header on each POST so a retry returns the first result instead of a duplicate. Key managers get weekly reminders for keys expiring within 14 days or not rotated in 180, and the hub flags a key whose daily calls jump to five times its weekly average or that is still being called after it was revoked. For webhooks, keep the signing secret that is shown once, verify the X-Awra-Signature header on every delivery, and use the Webhook Sandbox to check that your receiver rejects stale or replayed messages.

QuickBooks sync is useful because finance teams should not retype operational data. AWRA pushes suppliers, items, purchase orders, customers, issued invoices, payments received and tax codes to QuickBooks Online, and each needs a clean mapping and a monitored job; journals, supplier bills and credit notes stay in AWRA.

When sync fails, do not patch the database manually. Read the sync health, review the external error, fix the mapping or source record, retry safely, then reconcile AWRA and QBO totals.

In practice, a batch of purchase orders shows as failed under Sync status because their supplier is not in QuickBooks yet. Retrying now fails the same way; the fix is order: sync suppliers first, then purchase orders. AWRA also refuses a push before sending anything when two suppliers or two items share a name, and lists the duplicates to rename. Failed records retry on their own, checked every 15 minutes with a doubling wait, up to five attempts, after which the people who manage integrations are told weekly until the list is empty. Once the cause is fixed, press Retry failed now. Then use Compare balances with QuickBooks: because journals are not pushed, a difference there usually means a posting made in one system only, not a sync failure.