So you’re considering an API integration with ClickHome. Below is some information you’ll need to know.
ClickHome Plus
Before we get started on integration methods it will be useful to have some background on ClickHome Plus and the role it will play in your ClickHome API integration, as there may be implications to your security policy.
ClickHome Plus (CHPlus) is an event queuing system hosted in AWS. It handles notification of all update events that occur in your ClickHome system to a central point. It is the ClickHome event management system and is a 'hub-and-spoke' system servicing all ClickHome instances. It is built on top of the AWS SQS event queueing system as it provides a secure and reliable solution for ClickHome’s integration needs. CHPlus makes ClickHome events available for both SASS and on-premise systems, providing a single generic, supportable solution for the integration needs of all our clients.
Other Systems that need to perform actions, updates or integration based on particular ClickHome events can be subscribed to the relevant events, and CH will forward the events on as they are processed from the queue.
Figure 1: ClickHome Plus is a centralised hub-and-spoke event management system
CHPlus has been developed as a centralised hub-and-spoke event management system in order to provide a single and central point of integration for Zapier and a growing list of commonly integrated SASS applications
For bespoke API integrations with individual ClickHome instances it is the central integration point for all outbound messaging from your ClickHome system; and for standard integrations with SASS applications (i.e. Zapier) CHPlus is the central integration point for both inbound and outbound messaging.
The process for outbound events from ClickHome via CHPlus can be summarised as follows:
- An event is triggered in ClickHome (e.g. a Contract is created)
- The event type and record id are sent to the CHPlus SQS event queue in AWS (encrypted + digital signature)
- CHPlus verifies the digital signature on the event matches the applicable ClickHome system
- CHPlus obtains a ClickHome API token by logging in to the applicable system (48hr time restricted token)
- CHPlus requests the event data via the ClickHome API
- CHPlus authenticates with subscribes systems (as required)
- CHPlus forwards the packaged event (with data) to subscribed systems
The process for inbound requests from Zapier and other SASS applications are peculiar to the application and can be provided on request.
Figure 2. A simplified diagram of how CHPlus fits in with your ClickHome system and ClickHome API integration.
CHPlus authenticates with and uses the same API (the ClickHome API) as any ClickHome user using the Desktop interface. A time restricted ClickHome API token is obtained by logging in with a username and password.Events
Once a ClickHome System (on-premise or hosted) is registered to ClickHome Plus the ClickHome Webleads Windows Service packages up and sends event messages (using https protocol) to the CHPlus SQS queue in AWS.
Event messages to the SQS queue are JSON formatted, and are encrypted and digitally signed by the originating system. Only if an event has a valid signature will CHPlus process an event. Events without a valid signature are ignored.
Standard ClickHome events for supported record types typically include a:
- Create Event
- Update Event; and
- Custom Event
A list of supported event types is provided below. For non-standard events custom event codes can be included with the 'event wrapper' so that the destination system can determine what action is required on receipt of the event.
The following outbound event types are supported for the different integration methods.
Record Type | Events (outbound) | Zapier | CHPlus |
| Master Contracts | Create, Update, Custom |  |  |
| Clients | Create, Update, Custom |  |  |
| Contacts | Create, Update, Custom |  |  |
| Contracts (jobs) | Create, Update, Custom |  |  |
| Tasks | Create, Update, Complete, Custom |  |  |
| Notes | Create, Custom |  |  |
| Tenders | Create, Draft Status, Client Review Status, Estimator Review Status, Edit Required status, Accepted Status, Locked Status, Contract Status, Client Approved Status, Rejected Status, Expired Status, Custom |  |  |
The following inbound event types are supported for the different integration methods.
Record Type | Events (inbound) | Zapier | CHPlus |
| Master Contracts | Update, Get | | |
| Clients | Create, Update | | |
| Contacts | Create, Update, Get | | |
| Contracts (jobs) | Create, Update, Get | | |
| Tasks | Create, Update, Get | | |
| Notes | Create, Update, Get | | |
| Web Enquiries | Create | | |
| User | Get |  |  |
Standard ClickHome events contain only a record id and event type code packaged up in the event wrapper (i.e. no data from the task, contact or client record). A number of custom fields are available for the inclusion of non-standard data.
After obtaining a ClickHome API token, CHPlus hits the ClickHome API for the applicable data. The JSON-formatted response is then wrapped in the event ‘wrapper’ and forwarded on to the subscribed systems:
- Zapier (for Zapier integrations); or
- Specified webhook(s); or
- Client event queue(s).
If you want to integrate via Zapier you’ll also need a paid Zapier account. Zapier accounts are priced depending on how many steps (or tasks) are used monthly. See the Zapier website for details and what applications are supported.
Webhooks
Subscriptions for webhooks can be created with or without authentication. CHPlus currently supports the following authentication methods:
- OAUTH2
- No authentication
If your preferred method of authentication is not available please discuss your requirements with your ClickHome consultant and provide specifications.Event queues
Receiving ClickHome events to your own event queue gives you complete control over how the events are handled.
Events can be sent all to one queue, or can be divided up between queues by entity type (or other criteria as required).
Integration Methods
There are two ways that you can integrate with ClickHome through the API:
- For lightweight integrations - Zapier; or
For more complex, heavy-duty integrations - ClickHome API (inbound)/ClickHome Plus (outbound)
We also support unauthenticated GET requests, where we can supply identifiers in the query string, for intra-server event notification.Pros and Cons
Integration Method | Pros | Cons |
| Zapier |
|
|
| Custom API |
|
|
Supported record types (entities)
The following record types are supported for the different integration methods.
Record type (entity) | Zapier | API |
| Master Contracts |  |  |
| Clients |  |  |
| Contacts |  |  |
| Contracts (jobs) + flexfields |  |  |
| Tasks + flexfields |  |  |
| Notes |  |  |
| Web enquiries |  |  |
| Tenders |  |  |
| Suppliers |  |  |
| Purchase Orders |  |  |
Your Environment
ClickHome is a highly-specialised software vendor, not an IT/network engineering consultancy. So if you want to integrate your systems with ClickHome, you’ll need to make sure your environment supports ClickHome/ClickHome Plus or be prepared to develop your own solution(s).
ClickHome Plus, as stated above, is shared by all instances of ClickHome and cannot be locked down to a VPN or run locally within a VPN. It exists in AWS for all Client systems and makes use of a large range of dynamic IP addresses.
We're happy to answer any specific technical questions on an as-needs basis, and attend workshops with your team to describe the nuts and bolts of how ClickHome and CHPlus work, but allowing them to work within your environment is the responsibility of your internal Infrastructure team.
Frequently Asked Questions (FAQ)
Is the integration via CHPlus real-time?
CHPlus has been developed with a focus on being a robust, secure integration platform rather than a near-real-time one. It is built on the AWS SQS queuing system which enables events to be captured (for the prevention of event loss) and processed in chronological order at a more controlled rate - it is not immediate. The queuing mechanisms can resulting in delays of several minutes under normal conditions and longer during periods of high traffic. You can expect small delays in the order of 5-10 minutes.
Can I use a VPN?
CHPlus can’t be locked down to a VPN as it needs to be available for all ClickHome client systems. You can theoretically restrict internet traffic to specific IP addesses, from previous experience this is not feasible due to the nature of AWS dynamic IP ranges.
Can I use a Proxy?
You can use a Proxy (i.e. Azure Proxy) in bypass mode only, however this does not add significant benefits.
Can I host CHPlus locally?
No. CHPlus has been designed as centralised server for all ClickHome clients it must remain available externally to connect to external systems.
Can I limit traffic to specific IP addresses?
AWS uses a large range of dynamic IP addresses which changes daily. In order to whitelist the applicable IP addresses you’d need to devise a system to lookup and whitelist the full range of IP addresses each day.
Figure 3: Requests to the ClickHome Webservice/API may be coming from a range of IP addresses.
Why do my ClickHome events need to go external?
ClickHome uses a single, centralised hub-and-spoke event management system in order to meet the widest possible integration needs of our Clients and a single update path for latest technologies. As a centralised system CHPlus provides a reliable and supportable platform whether you’re integrating with cloud-based or on-premise applications.
If you don’t want your data to go external you would need to develop an alternate in-house integration – we allow custom tables and have standard staging tables in our database for this reason. We also support unauthenticated GET requests to webhooks for intra-server event notification.
Why AWS?
AWS is the leading provider of infrastructure and due to its good reputation as a robust reliable and secure platform and for the functionality offered by its SQS queuing system. To learn more about the security benefits of AWS visit the AWS website (intro video).
Is any of my sensitive data stored in ClickHome Plus?
No. CHPlus does not store any of your confidential/sensitive client data or job data. Event messages to CHPlus include only event codes and record identifiers so that CHPlus can lookup the applicable information in ClickHome and send this on to the destination system.
If I can't use a Proxy or VPN how can I make ClickHome more secure?
ClickHome supports free Active Directory integration. Alternatively you can look into the SSO paid module. You can read more about SSO in the solution article.