Wave integration

What it does

The Wave integration connects TaskJuice to your clients' Wave accounting businesses. Once a client authorizes the connection, your workflows can create and update customers, build, approve, and send invoices and estimates, record payments received outside Wave, manage products and services, record income and expenses, and set up accounts and sales taxes. Webhook triggers fire when an invoice or estimate is approved, sent, viewed, paid, or goes overdue, and when a buyer pays through a Wave checkout. Two polling triggers watch for new invoices and new customers, which Wave sends no webhook for.

Connect a Wave account

Wave connects over OAuth with your own Wave application:

1. In the Wave Developer Portal, create an application and set its redirect URI to https://<your TaskJuice domain>/oauth/callback.
2. In TaskJuice, open Settings, then Integrations, then OAuth clients, and add a Wave client with the application's client ID and client secret.
3. Open Connections, choose Wave, and click Connect. Sign in to Wave and choose the business to share.

Every Wave step and trigger then has a Business dropdown. Pick the business the step works in. One Wave login can own several businesses, so check you picked the right one for the client.

Set up webhook triggers

Wave sends events to one endpoint per Wave application, and it has no API for registering webhooks, so you set it up once by hand. Wave only sends webhooks for businesses on a Wave Pro plan.

1. Add any Wave webhook trigger, such as Invoice Paid, to a workflow and copy the Event delivery URL from its panel. Every Wave webhook trigger in your workspace shares this URL.
2. In the Wave Developer Portal, open Webhooks and select your application.
3. Paste the URL as the Endpoint URL. Under Listening, tick the events you want, for example invoice.paid and invoice.overdue, and save.
4. Copy the webhook signing secret and save it on your Wave OAuth client in TaskJuice, under Settings, then Integrations, then OAuth clients. TaskJuice checks the x-wave-signature header on every delivery and rejects anything unsigned or older than five minutes.

One Wave application delivers events for every business connected through it. To make a trigger fire for one client only, set its Business ID to the business UUID that Wave's events carry as business_id. The Wave Developer Portal's webhook logs can be filtered by it. Leave the field empty to fire for every connected business.

Webhook events carry raw IDs, while Wave's API uses encoded IDs. To read the invoice behind an event with Get Invoice, map its Invoice ID with the expression $base64encode("Business:" & $trigger.business_id & ";Invoice:" & $trigger.data.invoice_id). Use Estimate: and data.estimate_id for estimates.

Triggers

Webhook triggers (instant, Wave Pro):

• Invoice Approved, Invoice Sent, Invoice Viewed, and Invoice Overdue fire as an invoice moves through its life.
• Invoice Paid, Invoice Partially Paid, and Invoice Overpaid fire on each payment, with the amount paid and the balance left.
• Estimate Approved, Estimate Sent, Estimate Viewed, Estimate Accepted, Estimate Acceptance Reset, and Estimate Expired follow an estimate from draft to the customer's answer.
• Estimate Deposit Paid, Estimate Deposit Partially Paid, and Estimate Deposit Overpaid fire on deposit payments.
• Checkout Paid fires when a buyer pays through a Wave checkout link, with the buyer's contact details.

Polling triggers:

• New Invoice checks the chosen business for newly created invoices, every 5 minutes by default.
• New Customer checks the chosen business for newly created customers, every 5 minutes by default.

Polling triggers emit one run per check with every new record in items. Add a Loop node to handle each record on its own. Records that already exist when you publish do not fire.

Actions

• Customers: Create Customer, Update Customer, Delete Customer, Get Customer, Find Customer by Email, and List Customers.
• Invoices: Create Invoice (one product line, picked from dropdowns), Create Invoice with Line Items (a list of lines, for example mapped from an order), Update Invoice, Approve Invoice, Send Invoice, Mark Invoice as Sent, Record Invoice Payment, Get Invoice, List Invoices, and Delete Invoice.
• Estimates: Create Estimate, Approve Estimate, Send Estimate, Convert Estimate to Invoice, Get Estimate, and List Estimates.
• Products and services: Create, Update, Archive, Get, and List.
• Bookkeeping: Record Income or Expense books a sale or an expense against a bank account, and Create Money Transaction splits one across several accounts, for example a sale with tax and a processing fee.
• Setup and lookups: Create Account, List Accounts, Create Sales Tax, List Sales Taxes, List Vendors, and List Businesses.

Known limitations

• Wave answers every request with HTTP 200, including errors. TaskJuice reads the response body, so a refused request fails the step with Wave's own message.
• Webhooks need a Wave Pro plan on the client's business, and Wave skips events the connection's scopes do not cover. Wave sends no webhook for new invoices, new customers, or changes to customers and products.
• Wave retries a failed delivery up to six times over about 14 hours and pauses a webhook after 10 failures in a row. Design downstream steps to be safe to repeat; TaskJuice drops a redelivered event with the same event_id.
• Send Invoice needs an approved invoice and a business with Wave email sending enabled.
• Record Income or Expense and Create Money Transaction use Wave's beta money transaction API. Each needs a unique External ID; reuse one and Wave rejects the transaction.
• Wave's public API has no bills or vendor writes, so vendors are read-only.