QuickBooks Online Webhooks

asyncapi: 3.0.0
info:
  title: QuickBooks Online Webhooks
  version: "1.0.0"
  description: >-
    QuickBooks Online Webhooks provide near real-time notifications when data
    changes in a QuickBooks Online company. When an entity is created, updated,
    merged, deleted, or voided, Intuit sends an HTTP POST notification to your
    registered endpoint. Webhook notifications are delivered as JSON payloads
    and are signed with an HMAC-SHA256 signature using your webhook verifier
    token. Your endpoint must respond with an HTTP 200 status within 10 seconds.
    Notifications may be batched, delivering multiple entity change events in a
    single payload. Notifications are sent on a best-effort basis and may arrive
    out of order; your application should use the query API to retrieve the
    current state of changed entities.
  termsOfService: https://developer.intuit.com/app/developer/qbo/docs/learn/terms-of-service
  contact:
    name: Intuit Developer Support
    url: https://help.developer.intuit.com
    email: developer-support@intuit.com
  license:
    name: Intuit Developer Terms of Service
    url: https://developer.intuit.com/app/developer/qbo/docs/learn/terms-of-service
  externalDocs:
    description: QuickBooks Webhooks Documentation
    url: https://developer.intuit.com/app/developer/qbo/docs/develop/webhooks
  tags:
    - name: accounting
      description: Accounting entity change events
    - name: webhooks
      description: Webhook notification delivery

defaultContentType: application/json

servers:
  yourEndpoint:
    host: "{yourDomain}"
    protocol: https
    description: >-
      Your application's webhook endpoint. This URL is registered in the
      Intuit Developer portal under the Webhooks section of your app settings.
      Intuit sends HTTP POST requests to this URL when entity changes occur.
    variables:
      yourDomain:
        description: Your application's domain that receives webhook notifications
        default: api.example.com

channels:
  webhookNotification:
    address: /your-webhook-endpoint
    title: QuickBooks Webhook Notification Channel
    description: >-
      The channel through which Intuit delivers webhook notifications to your
      application. Your endpoint must accept POST requests and respond with
      HTTP 200 within 10 seconds. Failed deliveries are retried, but
      notifications are delivered on a best-effort basis.
    messages:
      webhookEvent:
        $ref: "#/components/messages/WebhookNotification"

operations:
  receiveWebhookNotification:
    action: receive
    channel:
      $ref: "#/channels/webhookNotification"
    title: Receive Webhook Notification
    summary: Receive entity change notifications from QuickBooks Online
    description: >-
      Your application receives webhook notifications when entities in a
      QuickBooks Online company are created, updated, merged, deleted, or
      voided. The notification payload contains metadata about the changes
      but not the full entity data. Your application should use the
      QuickBooks Online Accounting API to query for the current state of
      changed entities.
    messages:
      - $ref: "#/channels/webhookNotification/messages/webhookEvent"
    security:
      - type: httpApiKey
        name: intuit-signature
        in: header
        description: >-
          HMAC-SHA256 signature of the payload body using your webhook
          verifier token as the key. Your application must validate this
          signature to verify the notification came from Intuit. Compute
          the HMAC-SHA256 hash of the raw request body using your verifier
          token, then Base64 encode the result and compare it with the
          intuit-signature header value.

components:
  messages:
    WebhookNotification:
      name: WebhookNotification
      title: Webhook Notification
      summary: >-
        A batch of entity change notifications from QuickBooks Online
      description: >-
        Contains one or more entity change events grouped by company (realm).
        Each event describes a single entity change operation. Multiple events
        for different entities and different companies may be included in a
        single notification delivery.
      contentType: application/json
      headers:
        type: object
        properties:
          intuit-signature:
            type: string
            description: >-
              HMAC-SHA256 signature of the request body, Base64 encoded.
              Used to verify the notification originated from Intuit.
        required:
          - intuit-signature
      payload:
        $ref: "#/components/schemas/WebhookPayload"

  schemas:
    WebhookPayload:
      type: object
      description: >-
        The top-level webhook notification payload containing event
        notifications grouped by company.
      properties:
        eventNotifications:
          type: array
          description: >-
            Array of event notification groups, one per QuickBooks Online
            company that has changes.
          items:
            $ref: "#/components/schemas/EventNotification"
      required:
        - eventNotifications

    EventNotification:
      type: object
      description: >-
        A group of entity change events for a single QuickBooks Online company.
      properties:
        realmId:
          type: string
          description: >-
            The QuickBooks Online company ID (realm ID) where the changes
            occurred.
          examples:
            - "1234567890"
        dataChangeEvent:
          $ref: "#/components/schemas/DataChangeEvent"
      required:
        - realmId
        - dataChangeEvent

    DataChangeEvent:
      type: object
      description: >-
        Contains the array of entity change events for a company.
      properties:
        entities:
          type: array
          description: Array of individual entity change records
          items:
            $ref: "#/components/schemas/EntityChange"
      required:
        - entities

    EntityChange:
      type: object
      description: >-
        Describes a single entity change event. Contains the entity name,
        entity ID, the type of operation, and the time of the last update.
        Does not contain the full entity data; use the Accounting API to
        retrieve current entity state.
      properties:
        name:
          type: string
          description: >-
            The type of entity that changed. Corresponds to QuickBooks Online
            entity names.
          enum:
            - Invoice
            - Customer
            - Item
            - Payment
            - Account
            - Bill
            - BillPayment
            - CreditMemo
            - Deposit
            - Employee
            - Estimate
            - JournalEntry
            - Purchase
            - PurchaseOrder
            - RefundReceipt
            - SalesReceipt
            - TimeActivity
            - Transfer
            - Vendor
            - VendorCredit
            - Budget
            - Class
            - Department
            - PaymentMethod
            - Preferences
            - TaxAgency
            - TaxCode
            - TaxRate
            - Term
          examples:
            - Invoice
            - Customer
            - Payment
        id:
          type: string
          description: The unique identifier of the changed entity
          examples:
            - "1234"
        operation:
          type: string
          description: >-
            The type of operation that occurred on the entity
          enum:
            - Create
            - Update
            - Merge
            - Delete
            - Void
            - Emailed
          examples:
            - Create
            - Update
        lastUpdated:
          type: string
          format: date-time
          description: >-
            The date and time when the entity was last updated, in ISO 8601
            format (e.g., 2025-10-10T14:20:30.000Z). Use this timestamp to
            determine the order of changes and whether you need to re-query
            the entity.
          examples:
            - "2025-10-10T14:20:30.000Z"
        deletedId:
          type: string
          description: >-
            For merge operations, this is the ID of the entity that was
            deleted (merged into the entity identified by the id field).
      required:
        - name
        - id
        - operation
        - lastUpdated