Configuring Zoho for Integration With Aimbase


Note:

Executing the steps below does not automatically make your leads from Aimbase flow into your Zoho CRM. In order to receive your leads within Zoho, your manufacturer must approve the data flow and the Rollick Center of Excellence must enable the integration.

Overview

The purpose of this document is to define the steps required for a client to set up the ZOHO lead and disposition integration for their platform.                      



Lead Integration

First thing that will need to be done to setup a Zoho integration with Aimbase is to set the fields it would expect to receive.

Aimbase will need the Client ID and Secret to for integration setup

        a. Navigate to the ZOHO API Console App

        b. Add Client - Choose Server Self Client (dealer)

   


       c. Add Aimbase as the Client Name & https://www.aimbase.com as the Authorized Redirect URL.



      d. Once Aimbase has been added as an application you can find the Client ID and Secret by clicking into the application you just created and navigate to the Client Secret tab.



While the Rollick team works to setup Aimbase to send data to your Zoho account, you can begin prepping Zoho to receive the data from Aimbase with the instruction from the section below.



Zoho Field Set Up   

This step sets up the ability for the data Aimbase sends to your CRM to be organized and labeled appropriately.

1. Go to CRM.


2. Click on the gear for Settings.

3. Under Customization Select Modules and Fields.

4. Select the Leads Module.

5. Under the Fields tab select "+ Create & Edit Fields"

6. From here you will need to drag and drop the required field type from the New Fields Tray on the left to the Description information section on the right.

 


         The fields and field types that are listed in the table below need to be added to the description section. 


Field Name

Field Type

Lead Type

Single Line

Lead Category

Single Line

Brand

Pick List

Lead Campaign

Single Line

Event

Single Line

Medium

Single Line

Comment

Multi Line



7. Name the field name indicated in the table and define the Field Properties as required for that field.

8. Click Save Layout.

9. This table is a complete list (including the fields added in step #6) of what is set up to automatically map from Aimbase to Zoho: 

  1. Include this as the default mapping from Zoho to Aimbase
  2. Optionally customize fields as you wish within Zoho

Zoho

Aimbase

First Name

First Name

Last Name 

Last Name

Company 

Company

Lead Source 

Lead Source

Phone

Home Phone

Mobile

Mobile Phone

Fax

Fax

Email

Email

Street

Address 1

City 

City

State

State

Zip Code

Postal Code

Country 

Country

Lead Type

Lead Type

Lead Category

Lead Category

Brand

Brand

Lead Campaign

Lead Campaign

Event

Event 

Medium

Medium

Comment

Comment

 



 Disposition Integration

When Aimbase sends a lead to your Zoho CRM instance, Aimbase records the Zoho record Id that Zoho returns. This guide explains how to configure a Zoho webhook so that whenever a salesperson updates the lead's status in Zoho, that update is posted back to Aimbase. This is what allows Aimbase to report on what happened to each lead after it was delivered.

Setting this up is a two-part process inside Zoho CRM:

  1. Create a Webhook - defines where the data is sent and what is sent. This must be set up prior to creating the workflow rule. 
  2. Create a Workflow Rule - defines when the webhook fires.

IMPORTANT  A webhook on its own does nothing. It will only fire if it is attached to a Workflow Rule as an Instant Action. Section 4 covers this and must not be skipped.

1.  Provide Rollick with Status Mapping

Log in Before seeting up the webhook, please provide all values that may be sent to Rollick in the Lead_Status field to the COE (clientsupport@rollick.io) so the appropriate mapping can be set up. 


2. Navigate to the Webhooks screen

Log in to Zoho CRM as an administrator, then follow the path below. The Setup area is reached from the gear icon in the top-right of Zoho CRM.  Setup > Automation > Actions > Webhooks. 



 Open the Webhooks tab. Click Configure Webhook to create a new one, or click an existing webhook's name in the list to edit it.


2. Configure the webhook

Complete the webhook form using the values in the table below.

Field

Value

Notes

Name

LeadWebhook

Any descriptive name. 'LeadWebhook' is recommended for consistency.

Description

(optional)

Free text, e.g. 'Sends lead status changes to Aimbase'.

Method

POST

Must be POST. No other method is supported.

URL to Notify

https://crmintegration.aimbase.net/api/disposition?source=ZOHO

PRODUCTION endpoint. See the callout below.

Authorization Type

General

No authentication is required. Leave as General; do not select Connection.

Module

Leads

Must be Leads. The payload merge fields depend on this selection.

Module Parameters

(leave empty)

Not used. All data is supplied through the Body.

Custom Parameters

(leave empty)

Not used.

Body - Type

Raw

Select Raw, not Form-Data or x-www-form-urlencoded.

Body - Format

JSON

Must be JSON.

 

Use the Production URL note below. 

Environment

URL to Notify

Production 

https://crmintegration.aimbase.net/api/disposition?source=ZOHO

 

IMPORTANT  Enter the URL exactly as shown, with no trailing spaces or line breaks. The ?source=ZOHO portion is mandatory - Aimbase uses it to map the request and it will be rejected without it.


3. Set the Body Payload

Set Type to Raw and Format to JSON, then paste the following into the body editor exactly as shown. The ${Leads.*} entries are Zoho merge fields that Zoho replaces with the actual lead values when the webhook fires.

{
     "Lead_Id": "${Leads.Lead Id}",
     "Lead_Status": "${Leads.Lead Status}",
     "Modified_By": "${Leads.Modified By}",
     "Modified_Time": "${Leads.Modified Time}"
 }

Reference

The table below describes how Aimbase uses each field in the payload.

Field

Required

Zoho merge field

How Aimbase uses it

Lead_Id

Required

${Leads.Lead Id}

The Zoho record Id. Aimbase matches this against the Id captured when the lead was originally delivered. If this field is missing or empty the request is rejected.

Lead_Status

Required

${Leads.Lead Status}

The lead's current status in Zoho. This becomes the disposition status reported in Aimbase. Technically accepted if absent, but the disposition is then recorded with an empty status and carries no reporting value - always include it.

Modified_By

Optional

${Leads.Modified By}

The Zoho user who made the change. Recorded as the dealership user against the disposition. Defaults to blank if omitted.

Modified_Time

Optional

${Leads.Modified Time}

When the change was made. Used as the disposition entry date. If omitted or unparseable, Aimbase substitutes the time the webhook was received.

 TIP  Any additional fields you add to the JSON body are ignored rather than causing an error, so it is safe to extend the payload. However, do not rename or remove Lead_Id.

Click Save to store the webhook.


4. Navigate to the Webhooks screen Create the Workflow Rule that fires the webhook

REQUIRED STEP  Saving the webhook does not activate it. Zoho only sends the webhook when a Workflow Rule triggers it. Without this step no dispositions will ever reach Aimbase.

Zoho guides you through the rule in stages - WHEN, CONDITION and ACTIONS. Navigate to the Workflow Rules screen and click Create Rule:

Setup   >  Automation  >   Workflow Rules  >  Create Rule

Step 1 - Name the rule

In the Create New Rule dialog set Module to Leads and enter a Rule Name such as 'Send Lead Status to Aimbase'. The Description is optional. Click Next.


Step 2 - WHEN: choose the trigger

Configure the trigger exactly as follows:

  • Execute this workflow rule based on: Record action
  • Action: Edit
  • Scope: Specific field(s) gets modified
  • Field: Lead Status
  • Modified to: any value

Selecting 'any value' ensures every status change is reported, rather than only transitions to one specific status. Click Next.


Step 3 - CONDITION: choose which leads

When asked which leads the rule should apply to, select All Leads and click Done. Restricting this to certain conditions risks silently dropping dispositions for leads Aimbase is expecting updates on.


Step 4 - Add the webhook as an Instant Action

Under Instant Actions, open the action menu and choose Webhook.



Step 5 - Associate the webhook

Tick LeadWebhook - the webhook created in Section 3 - and click Associate. Confirm the URL shown in this list is the correct endpoint before associating.

Step 6 - Save the rule

Review the completed rule. It should read 'executed when Lead Status is modified to any value', 'executed for all leads', and show LeadWebhook under Instant Actions. Click Save.



5. Verify the configuration

  1. Open a lead in Zoho CRM that was originally delivered by Aimbase.
  2. Change the Lead Status to a different value and save the record.
  3. In Zoho, go to Setup > Automation > Actions > Webhooks and review the webhook's execution history to confirm a successful call was made.
  4. Confirm with Rollick's COE team (clientsupport@rollick.io) that the disposition was received.

NOTE  Status changes made to leads that did not originate from Aimbase - for example leads created directly in Zoho - are accepted and safely ignored. This is expected behaviour and is not an error.

6. Troubleshooting

Symptom

What to check

Zoho reports a failed or non-200 response

Confirm the URL is exactly correct, including ?source=ZOHO, and that Method is POST.

Webhook never fires

The Workflow Rule is missing, inactive, or the webhook was not added as an Instant Action.

Dispositions are not appearing in Aimbase

Confirm Lead_Id is present in the body and that the lead was originally delivered by Aimbase. Leads created directly in Zoho have no matching record and are ignored.

Status arrives blank in Aimbase

Lead_Status is missing from the JSON body or the merge field was mistyped.

Timestamps look wrong

Modified_Time is missing or in an unexpected format, so the received time is being used instead.

 

If the issue persists, contact the Rollick COE team clientsupport@rollick.io with your dealership name, the Zoho Lead Id you were testing with, and the approximate time of the test.