> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# QuickBooks Online Webhook Setup Guide

> Configure QuickBooks Online to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/quickbooksonline#getting-started) on the QuickBooks Online connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Retrieve the Native Webhook URL from StackOne</h2>

  <p>The <strong>Native Webhook URL</strong> is a computed field on the linked account. It is generated once the account has been linked, and you paste it into the Intuit Developer Portal in the next section.</p>

  <Steps>
    <Step title="Open the linked account and copy the URL">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Open the linked account in StackOne Hub and copy the <strong>Native Webhook URL</strong> value. Keep it private — the URL includes a delivery token.</p>

        <ul>
          <li>Open the linked account in StackOne Hub.</li>
          <li>Copy the value from <strong>Native Webhook URL</strong>.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Configure the webhook in the Intuit Developer Portal</h2>

  <p>QuickBooks Online webhooks are set up in the Intuit Developer Portal against the app you use to connect QuickBooks. The endpoint is shared by every company connected through that app.</p>

  <Steps>
    <Step title="Open the Webhooks page for your app">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Sign in to the <a href="https://developer.intuit.com" target="_blank" rel="noopener noreferrer">Intuit Developer Portal</a>, then open your app's webhook settings.</p>

        <ul>
          <li>From the upper-right menu, select <strong>My Hub</strong> > <strong>App dashboard</strong>.</li>
          <li>Open the app you use to connect QuickBooks Online.</li>
          <li>In the left navigation pane, select <strong>Webhooks</strong>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Select the matching environment">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The Webhooks page has separate <strong>Development</strong> and <strong>Production</strong> tabs. Configure the tab that matches your connected company — a sandbox company uses <strong>Development</strong>, a live company uses <strong>Production</strong>. A subscription added under the wrong tab never fires.</p>

        <ul>
          <li>Select <strong>Development</strong> for a sandbox company, or <strong>Production</strong> for a live company.</li>
        </ul>
      </div>
    </Step>

    <Step title="Add the endpoint URL">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Under <strong>Set up endpoints</strong>, paste the StackOne Native Webhook URL as the endpoint that receives notifications.</p>

        <ul>
          <li>Paste the copied Native Webhook URL into the <strong>Endpoint URL</strong> field.</li>
        </ul>
      </div>
    </Step>

    <Step title="Turn off the cloud event payload format">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Leave <strong>Enable cloud event payload format</strong> turned off. When it is on, QuickBooks Online wraps deliveries in a different payload structure that this connector does not recognize, and events are silently dropped.</p>

        <ul>
          <li>Make sure the <strong>Enable cloud event payload format</strong> toggle is off.</li>
        </ul>
      </div>
    </Step>

    <Step title="Select the entities to receive">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Under <strong>Subscribed events</strong>, choose which entities (and which operations — Create, Update, Delete, Merge, Void, Emailed) should send notifications. Only the entities you enable here are delivered.</p>

        <ul>
          <li>Enable notifications for the entities you want, for example <strong>Customer</strong>, <strong>Invoice</strong>, <strong>Payment</strong>, <strong>Bill</strong>, <strong>Vendor</strong>, and <strong>Item</strong>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Save and copy the Verifier Token">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Save the configuration, then copy the Verifier Token that Intuit shows so StackOne can validate delivery signatures.</p>

        <ul>
          <li>Click <strong>Save</strong>.</li>
          <li>Turn on <strong>Show verifier token</strong> and copy the value shown below the Endpoint URL.</li>
          <li>Paste it into the <strong>Webhook Verifier Token</strong> field on the linked account in StackOne Hub. The token is shown here whenever you need it.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>QuickBooks Online sends a single generic change notification for every entity change, so StackOne exposes one event — <strong>Data Changed</strong> (`data.changed`) — that carries every create, update, delete, merge, void, or email across all subscribed entities. You choose which entities are delivered in the Intuit Developer Portal (previous section); StackOne forwards the raw batch and, for each changed entity, tells you which action fetches the full record.</p>

  <Steps>
    <Step title="Data Changed">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Fired whenever one or more subscribed entities change. One delivery can batch several entities (and, rarely, several companies) at once.</p>

        <ul>
          <li><strong>Data Changed</strong> (`data.changed`) — Fired when any subscribed QuickBooks Online entity is created, updated, deleted, merged, voided, or emailed.</li>
        </ul>
      </div>
    </Step>

    <Step title="Choose entities to subscribe to">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The following entities support webhooks in QuickBooks Online. Enable the ones you need in the Intuit Developer Portal.</p>

        <ul>
          <li>Account, Bill, BillPayment, Budget, Class, CreditMemo, Currency, Customer, Department, Deposit, Employee, Estimate, Invoice, Item, JournalCode, JournalEntry, Payment, PaymentMethod, Preferences, Purchase, PurchaseOrder, RefundReceipt, SalesReceipt, TaxAgency, Term, TimeActivity, Transfer, Vendor, VendorCredit.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how QuickBooks Online delivers events to StackOne.</p>

  <Steps>
    <Step title="Review the batched payload">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The payload is an `eventNotifications` array. Each entry has a `realmId` (the Company ID that owns the changes) and a `dataChangeEvent.entities` array listing every entity that changed for that company in this delivery.</p>

        <ul>
          <li>A single delivery can contain multiple entity types, and — rarely — multiple companies. StackOne forwards the full batch untouched.</li>
        </ul>
      </div>
    </Step>

    <Step title="Verify the signature">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>QuickBooks Online signs each delivery so you can confirm it came from Intuit.</p>

        <ul>
          <li>Each request carries an `intuit-signature` header — a base64-encoded HMAC-SHA256 digest of the raw request body, keyed by your <strong>Webhook Verifier Token</strong>.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.