Agent skill
QuickBooks Webhooks Skill
Receive and verify QuickBooks Online (Intuit) webhooks. Use when setting up QuickBooks webhook handlers, debugging intuit-signature verification with the Verifier Token, migrating from the legacy eventNotifications payload to the CloudEvents format, or handling accounting events like qbo.account.created.v1, qbo.salesreceipt.updated.v1, and qbo.customer.merged.v1.
Install this skill
npx skills add hookdeck/webhook-skills --skill quickbooks-webhooks
When to Use This Skill
- How do I receive QuickBooks Online webhooks?
- How do I verify the
intuit-signatureheader with my Verifier Token? - Why is my QuickBooks webhook signature verification failing?
- How do I handle the new CloudEvents payload (
qbo.account.created.v1) and the legacyeventNotificationspayload? - How do I process QuickBooks webhooks for multiple companies (realm IDs) in one notification?
Verification (core)
Intuit signs the raw request body with HMAC-SHA256 keyed on your app's Verifier Token, base64-encodes the digest, and sends it in the intuit-signature header. There is no timestamp in the signed content, and the scheme is identical for both payload formats (CloudEvents deliveries also send intuit-signature-algorithm: HMAC-SHA256 and an intuit-signature-id, which you don't need to verify). Read the raw body before JSON parsing and compare timing-safe. Intuit's Java SDK has WebhooksService.verifyPayload; in other languages, verify manually.
Node:
const crypto = require('crypto');
function verifyQuickBooksSignature(rawBody, signature, verifierToken) {
if (!signature) return false;
const expected = crypto.createHmac('sha256', verifierToken).update(rawBody).digest('base64');
try {
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
} catch {
return false; // length mismatch = invalid
}
}
Python:
import hmac, hashlib, base64
def verify_quickbooks_signature(raw_body: bytes, signature: str, verifier_token: str) -> bool:
if not signature:
return False
expected = base64.b64encode(hmac.new(verifier_token.encode(), raw_body, hashlib.sha256).digest())
return hmac.compare_digest(signature.encode(), expected)
Respond with 200 within 3 seconds. Intuit retries failures (10s, 20s, 30s, 5m, 20m, 2h, 4h, 6h, then every 6h) and may hold back later events until the first one is acknowledged. Queue the work and process it asynchronously.
For complete handlers with route wiring, event dispatch, and tests, see:
Payload Structure
Intuit sends one of two formats, chosen per app by the Enable cloud event payload format toggle on the app's Webhooks page in the Intuit Developer portal. It was off by default on a test app checked in November 2026, so don't assume either format. Both carry the same intuit-signature.
CloudEvents (toggle on): Content-Type: application/cloudevents-batch+json and intuit-notification-schema-version: 2.0 in a November 2026 test delivery, and a body that is a JSON array of events, which can cover several companies (realm IDs) in one delivery. Treat the body as an array even when it holds one event. Payloads are thin: fetch the full record from the Accounting API using intuitentityid and intuitaccountid.
[
{
"specversion": "1.0",
"id": "88cd52aa-33b6-4351-9aa4-47572edbd068",
"source": "intuit.dsnBgbseACLLRZNxo2dfc4evmEJdxde58xeeYcZliOU=",
"type": "qbo.account.created.v1",
"datacontenttype": "application/json",
"time": "2025-09-10T21:31:25.179851517Z",
"intuitentityid": "1234",
"intuitaccountid": "310687",
"data": {}
}
]
Legacy (toggle off): Content-Type: application/json and intuit-notification-schema-version: 1.0 in a November 2026 test delivery, and a JSON object:
{"eventNotifications":[{"realmId":"310687","dataChangeEvent":{"entities":[{"id":"1234","operation":"Create","name":"Account","lastUpdated":"2026-11-18T16:08:22.702Z"}]}}]}
The legacy format has no type string: the entity name plus operation identify the event. The examples normalize both shapes into one event list, and the same signature check covers both.
Common Event Types
type has the format qbo.<entity>.<operation>.v1, all lowercase, with multi-word entities run together (qbo.salesreceipt.updated.v1). Intuit's docs print only four type strings, listed below, but the Developer portal's Send test events picker lists 105, covering every entity and operation in overview.md:
| Event type | Triggered When |
|---|---|
qbo.account.created.v1 | An account is created |
qbo.customer.merged.v1 | Two customers are merged (data.deletedid holds the removed ID) |
qbo.salesreceipt.updated.v1 | A sales receipt is changed |
qbo.employee.created.v1 | An employee is created |
The operation segment is one of created, updated, deleted, merged, void (not voided) or emailed, depending on the entity. The examples handle created, updated, deleted and merged by name and send void, emailed and anything new to a default branch that re-fetches the record.
Environment Variables
QUICKBOOKS_WEBHOOK_VERIFIER_TOKEN=your_verifier_token # Developer dashboard > your app > Webhooks > Verifier Token
Development (sandbox) and Production each have their own Verifier Token. Use the one that matches the environment that sends to the endpoint.
Local Development
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 quickbooks --path /webhooks/quickbooks
Reference Materials
- references/overview.md - Payload formats (CloudEvents and legacy), event types, supported entities
- references/setup.md - Configure webhooks in the Intuit Developer dashboard, get the Verifier Token
- references/verification.md - Signature verification details, gotchas, debugging