Module trigger.quickbooks
ballerinax/trigger.quickbooks Ballerina library
Overview
The QuickBooks trigger allows you to listen to QuickBooks webhook notifications.
After you subscribe for webhooks to receive event-triggered callbacks for entities that your application must listen to. QuickBooks webhooks automatically notify you whenever data changes in your end user’s QuickBooks Online company files.
Prerequisites
Before using this trigger in your Ballerina application, complete the following:
- Create a QuickBooks account.
- Add listener endpoint URL to QuickBooks webhooks.
- [Optional] Select and Save Entities and their events.
Compatibility
| Version | |
|---|---|
| Ballerina Language | Ballerina Swan Lake 2201.11.0 |
Quickstart
To use the QuickBooks trigger in your Ballerina application, update the .bal file as follows:
Step 1: Import the trigger
First, import ballerinax/trigger.quickbooks module into the Ballerina project as follows.
import ballerinax/trigger.quickbooks;
Step 2: Create a new trigger instance
Initialize the trigger by providing the app-specific verifier token (to validate the webhook notifications from the callback are from Intuit) and QuickBooks company IDs in the listener config and the port number where your trigger will be running. You can also pass an http:Listerner instance instead of the port number with the listener config. The app-specific verifier token is shown under webhooks section of your QuickBooks app after registering an endpoint URL. The QuickBooks companyId is shown in your app under the company list.
listener quickbooks:Listener quickBooksListener = new ( listenerConfig = { verificationToken: "<VERIFIER_TOKEN>", realmIds: ["<COMPANY_ID_01>", "<COMPANY_ID_02>"] }, listenOn = <PORT> );
If you don't provide a port it will use the default port which is 8090.
Step 3: Run the trigger service
-
Implement a service using the correct service type for the relevant event channel (e.g.,
quickbooks:CustomerService).The following is a sample service that listens to QuickBooks Customer events via the QuickBooks trigger:
service quickbooks:CustomerService on quickBooksListener { remote function onCustomerCreate(quickbooks:QuickBookEvent event) returns error? { // YOUR LOGIC ON THE EVENT } remote function onCustomerUpdate(quickbooks:QuickBookEvent event) returns error? {} remote function onCustomerDelete(quickbooks:QuickBookEvent event) returns error? {} remote function onCustomerMerge(quickbooks:QuickBookEvent event) returns error? {} } -
To compile and run the Ballerina program, issue the following command:
bal run
Step 4: Subscribe to a webhook topic with the URL of the service
For instructions to subscribe to a webhook topic with the URL of the service, see Intuit Developer Documentation - Webhooks.
Note:
- Locally, you can use ngrok to expose your web service to the internet and to obtain a public URL (For example: 'https://7745640c2478.ngrok.io').
- In Choreo, you can obtain this service URL from the
Invoke URLsection of theConfigure and Deployform underDeployview before App deployment.- Add a trailing
/to the end of public URL if it's not present.
Report issues
To report bugs, request new features, start new discussions, etc., go to the Ballerina Library repository
Useful links
- For more information go to the
trigger.quickbookspackage. - For example demonstrations of the usage, go to Ballerina By Examples.
- Chat live with us via our Discord server.
- Post all technical questions on Stack Overflow with the #ballerina tag.
Service types
trigger.quickbooks: AccountService
Triggers when a new event related to Quickbooks Account is received. Available actions: onAccountCreate, onAccountUpdate, onAccountDelete, and onAccountMerge.
onAccountCreate
function onAccountCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onAccountUpdate
function onAccountUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onAccountDelete
function onAccountDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onAccountMerge
function onAccountMerge(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: BillService
Triggers when a new event related to Quickbooks Bill is received. Available actions: onBillCreate, onBillUpdate, and onBillDelete.
onBillCreate
function onBillCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onBillUpdate
function onBillUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onBillDelete
function onBillDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: BillPaymentService
Triggers when a new event related to Quickbooks BillPayment is received. Available actions: onBillpaymentCreate, onBillpaymentUpdate, onBillpaymentDelete, and onBillpaymentVoid.
onBillpaymentCreate
function onBillpaymentCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onBillpaymentUpdate
function onBillpaymentUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onBillpaymentDelete
function onBillpaymentDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onBillpaymentVoid
function onBillpaymentVoid(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: BudgetService
Triggers when a new event related to Quickbooks Budget is received. Available actions: onBudgetCreate and onBudgetUpdate.
onBudgetCreate
function onBudgetCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onBudgetUpdate
function onBudgetUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: ClassService
Triggers when a new event related to Quickbooks Class is received. Available actions: onClassCreate, onClassUpdate, and onClassDelete.
onClassCreate
function onClassCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onClassUpdate
function onClassUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onClassDelete
function onClassDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: CreditMemoService
Triggers when a new event related to Quickbooks CreditMemo is received. Available actions: onCreditmemoCreate, onCreditmemoUpdate, onCreditmemoDelete, and onCreditmemoVoid.
onCreditmemoCreate
function onCreditmemoCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onCreditmemoUpdate
function onCreditmemoUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onCreditmemoDelete
function onCreditmemoDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onCreditmemoVoid
function onCreditmemoVoid(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: CurrencyService
Triggers when a new event related to Quickbooks Currency is received. Available actions: onCurrencyCreate and onCurrencyUpdate.
onCurrencyCreate
function onCurrencyCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onCurrencyUpdate
function onCurrencyUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: CustomerService
Triggers when a new event related to Quickbooks Customer is received. Available actions: onCustomerCreate, onCustomerUpdate, onCustomerDelete, and onCustomerMerge.
onCustomerCreate
function onCustomerCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onCustomerUpdate
function onCustomerUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onCustomerDelete
function onCustomerDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onCustomerMerge
function onCustomerMerge(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: DepartmentService
Triggers when a new event related to Quickbooks Department is received. Available actions: onDepartmentCreate, onDepartmentUpdate, and onDepartmentMerge.
onDepartmentCreate
function onDepartmentCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onDepartmentUpdate
function onDepartmentUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onDepartmentMerge
function onDepartmentMerge(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: DepositService
Triggers when a new event related to Quickbooks Deposit is received. Available actions: onDepositCreate, onDepositUpdate, and onDepositDelete.
onDepositCreate
function onDepositCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onDepositUpdate
function onDepositUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onDepositDelete
function onDepositDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: EmployeeService
Triggers when a new event related to Quickbooks Employee is received. Available actions: onEmployeeCreate, onEmployeeUpdate, onEmployeeDelete, and onEmployeeMerge.
onEmployeeCreate
function onEmployeeCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onEmployeeUpdate
function onEmployeeUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onEmployeeDelete
function onEmployeeDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onEmployeeMerge
function onEmployeeMerge(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: EstimateService
Triggers when a new event related to Quickbooks Estimate is received. Available actions: onEstimateCreate, onEstimateUpdate, and onEstimateDelete.
onEstimateCreate
function onEstimateCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onEstimateUpdate
function onEstimateUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onEstimateDelete
function onEstimateDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: InvoiceService
Triggers when a new event related to Quickbooks Invoice is received. Available actions: onInvoiceCreate, onInvoiceUpdate, onInvoiceDelete, and onInvoiceVoid.
onInvoiceCreate
function onInvoiceCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onInvoiceUpdate
function onInvoiceUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onInvoiceDelete
function onInvoiceDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onInvoiceVoid
function onInvoiceVoid(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: ItemService
Triggers when a new event related to Quickbooks Item is received. Available actions: onItemCreate, onItemUpdate, onItemDelete, and onItemMerge.
onItemCreate
function onItemCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onItemUpdate
function onItemUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onItemDelete
function onItemDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onItemMerge
function onItemMerge(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: JournalCodeService
Triggers when a new event related to Quickbooks JournalCode is received. Available actions: onJournalcodeCreate and onJournalcodeUpdate.
onJournalcodeCreate
function onJournalcodeCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onJournalcodeUpdate
function onJournalcodeUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: JournalEntryService
Triggers when a new event related to Quickbooks JournalEntry is received. Available actions: onJournalentryCreate, onJournalentryUpdate, and onJournalentryDelete.
onJournalentryCreate
function onJournalentryCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onJournalentryUpdate
function onJournalentryUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onJournalentryDelete
function onJournalentryDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: PaymentService
Triggers when a new event related to Quickbooks Payment is received. Available actions: onPaymentCreate, onPaymentUpdate, onPaymentDelete, and onPaymentVoid.
onPaymentCreate
function onPaymentCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPaymentUpdate
function onPaymentUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPaymentDelete
function onPaymentDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPaymentVoid
function onPaymentVoid(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: PaymentMethodService
Triggers when a new event related to Quickbooks PaymentMethod is received. Available actions: onPaymentmethodCreate, onPaymentmethodUpdate, and onPaymentmethodMerge.
onPaymentmethodCreate
function onPaymentmethodCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPaymentmethodUpdate
function onPaymentmethodUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPaymentmethodMerge
function onPaymentmethodMerge(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: PreferencesService
Triggers when a new event related to Quickbooks Preferences is received. Available action: onPreferencesUpdate.
onPreferencesUpdate
function onPreferencesUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: PurchaseService
Triggers when a new event related to Quickbooks Purchase is received. Available actions: onPurchaseCreate, onPurchaseUpdate, onPurchaseDelete, and onPurchaseVoid.
onPurchaseCreate
function onPurchaseCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPurchaseUpdate
function onPurchaseUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPurchaseDelete
function onPurchaseDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPurchaseVoid
function onPurchaseVoid(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: PurchaseOrderService
Triggers when a new event related to Quickbooks PurchaseOrder is received. Available actions: onPurchaseorderCreate, onPurchaseorderUpdate, and onPurchaseorderDelete.
onPurchaseorderCreate
function onPurchaseorderCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPurchaseorderUpdate
function onPurchaseorderUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onPurchaseorderDelete
function onPurchaseorderDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: RefundReceiptService
Triggers when a new event related to Quickbooks RefundReceipt is received. Available actions: onRefundreceiptCreate, onRefundreceiptUpdate, onRefundreceiptDelete, and onRefundreceiptVoid.
onRefundreceiptCreate
function onRefundreceiptCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onRefundreceiptUpdate
function onRefundreceiptUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onRefundreceiptDelete
function onRefundreceiptDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onRefundreceiptVoid
function onRefundreceiptVoid(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: SalesReceiptService
Triggers when a new event related to Quickbooks SalesReceipt is received. Available actions: onRefundreceiptCreate, onRefundreceiptUpdate, onRefundreceiptDelete, and onRefundreceiptVoid.
onRefundreceiptCreate
function onRefundreceiptCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onRefundreceiptUpdate
function onRefundreceiptUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onRefundreceiptDelete
function onRefundreceiptDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onRefundreceiptVoid
function onRefundreceiptVoid(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: TaxAgencyService
Triggers when a new event related to Quickbooks TaxAgency is received. Available actions: onTaxagencyCreate and onTaxagencyUpdate.
onTaxagencyCreate
function onTaxagencyCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onTaxagencyUpdate
function onTaxagencyUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: TermService
Triggers when a new event related to Quickbooks Term is received. Available actions: onTermCreate and onTermUpdate.
onTermCreate
function onTermCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onTermUpdate
function onTermUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: TimeActivityService
Triggers when a new event related to Quickbooks TimeActivity is received. Available actions: onTimeactivityCreate, onTimeactivityUpdate and onTimeactivityDelete.
onTimeactivityCreate
function onTimeactivityCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onTimeactivityUpdate
function onTimeactivityUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onTimeactivityDelete
function onTimeactivityDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: TransferService
Triggers when a new event related to Quickbooks Transfer is received. Available actions: onTransferCreate, onTransferUpdate, onTransferDelete and onTransferVoid.
onTransferCreate
function onTransferCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onTransferUpdate
function onTransferUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onTransferDelete
function onTransferDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onTransferVoid
function onTransferVoid(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: VendorService
Triggers when a new event related to Quickbooks Vendor is received. Available actions: onVendorCreate, onVendorUpdate, onVendorDelete and onVendorMerge.
onVendorCreate
function onVendorCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onVendorUpdate
function onVendorUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onVendorDelete
function onVendorDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onVendorMerge
function onVendorMerge(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
trigger.quickbooks: VendorCreditService
Triggers when a new event related to Quickbooks VendorCredit is received. Available actions: onVendorcreditCreate, onVendorcreditUpdate, and onVendorcreditDelete.
onVendorcreditCreate
function onVendorcreditCreate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onVendorcreditUpdate
function onVendorcreditUpdate(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
onVendorcreditDelete
function onVendorcreditDelete(QuickBookEvent event) returns error?Parameters
- event QuickBookEvent -
Listeners
trigger.quickbooks: Listener
attach
function attach(GenericServiceType serviceRef, () attachPoint) returns error?detach
function detach(GenericServiceType serviceRef) returns error?Parameters
- serviceRef GenericServiceType -
'start
function 'start() returns error?gracefulStop
function gracefulStop() returns error?immediateStop
function immediateStop() returns error?Records
trigger.quickbooks: DataChangeEvent
Record for set of QuickBook data changes
Fields
- entities QuickBookEvent[] - Set of QuickBook data changes
trigger.quickbooks: EventNotification
Record for event notification for a company.
Fields
- realmId string - Company Id
- dataChangeEvent DataChangeEvent - The event changes information
trigger.quickbooks: EventNotifications
Record for set of event notification for all companies.
Fields
- eventNotifications EventNotification[] - Set of event notification for all companies
trigger.quickbooks: ListenerConfig
Fields
- verificationToken string -
- realmIds string[] -
trigger.quickbooks: QuickBookEvent
Record for QuickBook data change.
Fields
- lastUpdated? string - The latest timestamp in UTC.
- name? string - The name of the entity that changed (customer, Invoice, etc.).
- deletedID? string - The ID of the deleted or merged entity (this only applies to merge events)
- id? string - The ID of the changed entity.
- operation? string - The type of the change.
Union types
trigger.quickbooks: GenericServiceType
GenericServiceType
Simple name reference types
trigger.quickbooks: CommonResponseType
CommonResponseType
trigger.quickbooks: GenericDataType
GenericDataType