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-signature header 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 legacy eventNotifications payload?
  • 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 typeTriggered When
qbo.account.created.v1An account is created
qbo.customer.merged.v1Two customers are merged (data.deletedid holds the removed ID)
qbo.salesreceipt.updated.v1A sales receipt is changed
qbo.employee.created.v1An 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Oct 28, 2026

View on GitHub →