Skip to main content

​
Overview

A Zoho Books connection in Tirdad stores encrypted credentials that allow the system to interact with your Zoho Books organization for:
  • Connecting to Zoho Books using OAuth
  • Syncing invoices from Tirdad to Zoho Books
  • Creating and matching contacts in Zoho Books when invoices sync
  • Receiving webhook notifications from Zoho Books
  • Reconciling invoice payments and voids between Zoho Books and Tirdad

​
Prerequisites

Before setting up your Zoho Books connection, ensure you have:
  1. Zoho Books Organization - Admin access to a Zoho Books organization with API access
  2. Zoho API Console Application - Client ID and Client Secret from Zoho API Console (or your region’s console)
  3. OAuth Redirect URI - The callback URL Tirdad uses for OAuth, registered exactly under your app’s authorized redirect URIs in Zoho
  4. Tirdad Environment - Valid Tirdad tenant and environment for the connection
  5. Webhook Secret - A strong value you invent (Zoho does not provide one by default). Type the exact same string in Zoho’s webhook settings and in Tirdad (recommended; used to verify X-Zoho-Webhook-Signature)

​
Step 1: Gather Zoho Books Credentials

​
Required Credentials

CredentialLocationRequiredPurpose
Client IDZoho API Console✅OAuth app identifier; starts the Zoho sign-in flow
Client SecretZoho API Console✅Completes token exchange after user consent
Redirect URIZoho API Console → Authorized Redirect URIs✅Must match Tirdad’s OAuth callback URL for your deployment and region
Organization IDZoho Books (organization settings / URL)✅Identifies which Zoho Books org Tirdad calls
Accounts serverZoho Accounts region✅OAuth and API host context (for example https://accounts.zoho.in, https://accounts.zoho.com)
Webhook SecretYou type it in Zoho Books (webhook action) and again in Tirdad—same string both placesRecommendedZoho does not auto-generate this; both sides must match for X-Zoho-Webhook-Signature verification

​
Finding Your Client ID and Client Secret

  1. Go to Zoho API Console (or your Zoho region’s API console).
  2. Create or open an application for Server-based Applications (or the application type your organization uses for Zoho Books).
  3. Copy the Client ID and Client Secret.
  4. Under Authorized Redirect URIs, add Tirdad’s OAuth callback (for example https://app.tirdad.ai/tools/integrations/oauth/ for Tirdad Cloud—use the exact URL your deployment shows if it differs).
  5. Save the application.
Zoho API Console — app details, homepage URL, and authorized redirect URI

​
Step 2: Configure Zoho Books Webhooks

Zoho Books uses webhook rules (when something happens) and actions (for example notify URL / POST to an endpoint). For a full integration, configure two webhooks:
  1. Invoices - So Tirdad can process paid and voided invoice events.
  2. Customers - So Tirdad can create customers when a customer is created in Zoho Books (workflow on the Customers module; customer inbound sync is on by default on the connection).
Both webhooks should use the same Tirdad URL pattern below. Use the tenant and environment IDs from the Tirdad dashboard for the workspace where the connection will live. Webhook URL Format: 
https://<your-tirdad-api-host>/v1/webhooks/zoho_books/<tenant_id>/<environment_id>
For Tirdad Cloud, the host is often https://api.tirdad.ai. Replace <tenant_id> and <environment_id> with your Tirdad IDs. For other regions or deployments, use the API base URL your organization was given (for example https://api.tirdad.ai). If webhooks return success but Tirdad does not update data, confirm the tenant and environment in the path match the environment where Zoho Books is connected.

​
Webhook secret (type the same value in Zoho and Tirdad)

Zoho Books does not give you a webhook signing secret to copy. The field is empty unless you fill it: you choose a strong secret (for example a long random string), then type that exact same characters everywhere it is asked for.
  1. Choose one secret and use it for both workflow webhooks (invoice and customer), so Tirdad only stores a single value.
  2. When you add the webhook action in Zoho, type that secret into Zoho’s webhook / signing secret field (wording varies by screen)—do not look for a value Zoho generated; there isn’t one by default.
  3. In Tirdad (Step 3), type the same secret into the Webhook secret field on the Zoho Books connection.
There is nothing to “copy from Zoho”—only the same string typed in Zoho and in Tirdad. It does not matter whether you enter it in Zoho or in Tirdad first, as long as both match. If you change the secret, update both places.

​
Webhook 1 — Invoices (Paid and Voided)

Create a workflow on the Invoice module (for example when an invoice is edited and status is updated) so changes such as Paid or Void are sent to Tirdad. Add a webhook immediate action that POSTs to your Tirdad webhook URL.
Zoho Books — Invoice workflow: status updates trigger webhook to Tirdad

​
Webhook 2 — Customers (Inbound Customer Sync)

Create a second workflow on the Customers module for customer created (all customers or your criteria), with a webhook action posting to the same Tirdad URL as the invoice rule. Customer inbound sync is on by default on the connection; turn it off only if you do not want new Zoho customers to create Tirdad customers.
Zoho Books — Customers workflow: customer created triggers webhook to Tirdad

​
Step 3: Create Zoho Books Connection

​
Using Tirdad Dashboard

You can create a Zoho Books connection from the Tirdad dashboard:
1

Navigate to Integrations

Go to Tirdad dashboard → Integrations → Zoho Books (or Accounting) → Connect / Add connection.
2

Enter connection details

Fill in Connection name, Client ID, and Client Secret from the Zoho API Console. Add your Zoho Books organization ID and the accounts server for your region (for example https://accounts.zoho.in or https://accounts.zoho.com). Copy the webhook URL from the modal into each Zoho Books webhook. In Webhook secret, type the same value you use in Zoho’s webhook / signing-secret field (character-for-character). You pick that value yourself—Zoho does not provide one. You can update this field later if you rotate the secret.
3

Complete OAuth

Complete sign-in and consent in Zoho. Tirdad exchanges the authorization code for tokens, stores them encrypted, and associates the connection with your Zoho organization. Access tokens refresh automatically.
4

Review sync settings

Invoice outbound sync and customer inbound sync are on by default for a new connection. Change them only if you do not want invoices pushed to Zoho or new Zoho contacts imported into Tirdad.
Tirdad — Connect to Zoho Books modal (credentials, org ID, accounts server, webhook URL and secret)

​
Customer Sync

Tirdad can keep customers aligned toward Zoho (with invoice sync) and from Zoho (via webhooks). On the connection, invoice outbound and customer inbound sync are on by default; you can turn either off if you do not want that behavior.

​
Tirdad → Zoho Books (contacts on the Zoho side)

Default: Invoice outbound sync is on by default (see Sending invoices to Zoho). If someone turned it off, enable it again on the connection to push invoices—and the related contacts—to Zoho. What happens: Whenever Tirdad creates an invoice in Zoho Books, it also creates or matches a contact in Zoho for that invoice’s Tirdad customer. You do not maintain that contact separately before the invoice sync runs.

​
Zoho Books → Tirdad (new customers in Tirdad)

Default: Customer inbound sync is on by default on the connection. Also required in Zoho: Inbound only works when Zoho can reach Tirdad. In Zoho Books, configure the customer created webhook from Step 2 so Zoho notifies Tirdad when customers are created. What happens: A new customer in Zoho Books can become a new customer in Tirdad. Vendor records are ignored. If the customer’s email already exists on a Tirdad customer, Tirdad links to that customer instead of creating a second one.

​
Invoice Sync

​
Sending invoices to Zoho (outbound)

Default: Invoice outbound sync is on by default on a new connection. Disable it only if you do not want Tirdad to create invoices in Zoho Books. What happens: After a Tirdad invoice is eligible to sync to your accounting system (same rules as other Tirdad accounting integrations), Tirdad creates a corresponding invoice in Zoho Books. You do not manually re-enter that invoice in Zoho.

​
How line items appear in Zoho

Zoho Books receives one line per Tirdad line so totals stay aligned:
  • Quantity is always 1 per line.
  • Rate is set to the full amount of that Tirdad line (so the line total in Zoho equals the Tirdad line amount).

​
Currency and exchange rates

Zoho Books uses an organization base currency. If the Tirdad invoice uses a different currency:
  1. In Zoho Books, open Settings → Currencies.
  2. Add that invoice currency if it is missing.
  3. Set a positive exchange rate from that currency to your base currency.
If this is missing or invalid, Zoho may reject the invoice Tirdad tries to create.

​
Invoice updates from Zoho (webhooks)

This applies when the Zoho invoice was originally created from Tirdad (so both systems are linked).
Event in ZohoWhat Tirdad does
Invoice paidRecords payment and updates the Tirdad invoice status (safe to retry if Zoho sends the event more than once).
Invoice voidedVoids the linked Tirdad invoice when the workflow allows it.
Other changes in Zoho (edits, partial updates, unrelated fields) are not continuously copied back into Tirdad; only these webhook-driven outcomes are handled.

​
Security Best Practices

​
Credential Management

  1. Environment separation - Use separate Zoho API applications or organizations for development and production where possible.
  2. Secret rotation - Rotate the Zoho Client Secret in the API Console if needed. For webhooks, set a new secret in both Zoho workflow actions and the Tirdad connection together.
  3. Encryption - Tirdad stores connection secrets encrypted at rest.

​
Webhook Security

  1. HTTPS only - Use HTTPS for the webhook URL.
  2. Signature verification - Store the same user-defined webhook secret on the Tirdad connection as in Zoho so Tirdad can verify X-Zoho-Webhook-Signature.
  3. Correct URL path - Incorrect tenant or environment in the URL prevents Tirdad from loading the connection even when the HTTP request succeeds.

​
Troubleshooting

IssueCauseSolution
Webhook does not update TirdadWrong tenant or environment in URLUse the exact tenant and environment IDs from Tirdad for the org where the connection exists
Invalid webhook signatureSecret mismatchThe string in Zoho’s webhook action and in Tirdad must be identical; update both sides if you rotate the secret
Invoice fails to sync to ZohoCurrency or exchange rateIn Settings → Currencies, add the invoice currency with a positive rate against base currency
New Zoho customer does not create Tirdad customerInbound off or missing webhookConfirm customer inbound is on (default is on); ensure the customer created webhook in Zoho targets the correct Tirdad URL
Paid in Zoho but Tirdad invoice unpaidMissing entity mappingThe Zoho invoice typically must have been created from Tirdad so entity integration mapping links both sides

​
Next Steps

After setting up your Zoho Books connection:
  1. Verify the connection - Confirm the connection shows as active in Tirdad.
  2. Test invoice sync - With outbound invoice sync on, create or finalize a test invoice and confirm it appears in Zoho Books.
  3. Test payment reconciliation - Mark the invoice paid in Zoho and confirm Tirdad reflects payment status.
  4. Test customer sync (optional) - With inbound customer sync on, create a customer in Zoho Books and confirm a customer appears in Tirdad.