Understanding HubSpot’s API and its uses

Depending on what sort of integration you want to build HubSpot allows integrations to be either private or public. Private integrations are specific to one account and would be suitable for an integration that is only going to be used by one company. Public integrations go on the HubSpot marketplace  and would be suitable for a company that wants their integration to be available to everyone, for example Google has a Google Calendar integration, to allow Google Calendar events to be created from within the HubSpot CRM.

To help with integration HubSpot provides client libraries for Node.JS, PHP, Ruby and Python. The reference documentation breaks the capabilities into the following areas:

• Account
• Analytics and Evemts
• Automation
• CMS (Customising the content management system)
• Conversations
• CRM (Managing the database of the businesses relationships and processes)
• Marketing
• Files
• Webhooks

Integration Options and Methods

When to opt for a built in integration vs a custom API integration will depend on various factors. If the integration is with another well used tool such as another CRM or a social media platform there will likely be an existing integration that can be used. A built in integration will generally require minimal setup and will be quick and easy to use. Any ongoing maintenance to keep the integration working will be handled by the integration provider. However you are limited to the functionality provided by the integration.

A custom integration is likely to be needed when integrating with your own systems, when integrating with a system that is not so widely used and therefore no built in integrations exist or when integrating with a system where the built in functionality does not meet your requirements. The advantage of a custom integration is it can be built exactly to your requirements, so can be highly customised and can be optimised for performance and scalability, however it requires technical expertise to build, time to develop and ongoing maintenance needs. The cost of a custom integration would be considerably higher than that of a built in integration.

Middleware and low-code platforms

When developing a custom integration there are various options. Direct API calls allow the most flexibility as all the API endpoints are available, with full control over how they are used, however calling the API directly requires the most technical knowledge and time to build. It requires proficiency in at least one programming language, an understanding how to work with RESTful APIs, including making HTTP requests, handling responses, and error handling, an understanding of the security risks and more general programming skills such as version control, testing, debugging and deploying. 

Middleware and low-code platforms are other options that play a significant role in simplifying integration processes by bridging gaps between different systems, reducing the need for extensive custom development, and enabling non-technical users to participate in the integration process. Here’s an overview of their roles and when each method is most appropriate.

Technical Requirements

HubSpot implements rate limiting on their API endpoints, this helps prevent abuse, reduces the load on their systems and allows them to implement paid tiers to monetise their services. It’s important to understand these rate limits and monitor the amount of API calls being made as when they are hit the integration will no longer be able to call the endpoints until the limit resets. It’s also important to take measures to ensure the API calls that are made are being done so efficiently, for example, using Webhooks to monitor changes rather than making regular API calls to poll for changes. If an API call fails, retry a limited number of times, increasing the duration between retries, and taking note of response messages from the API. Batch requests where possible, so instead of sending data one at a time, send all in one request. Cache responses for repetitive API calls, especially where the data doesn’t change frequently. If API requests don’t need to be made in real-time they can be queued to ensure they are within the rate limits.

Challenges and Considerations

The HubSpot API uses OAuth for secure authentication and HTTPS to protect data being transferred via the API. When developing an API integration it’s important to consider security risks. Any user inputs should be validated and sanitised to to prevent common vulnerabilities such as SQL injection and cross-site scripting. Ensure any data that is stored can only be accessed by users with the required roles and permissions. Avoid storing sensitive information unless absolutely necessary, and encrypt sensitive data securely.

Handling Errors

Handling errors is an important part of building an API integration. There are various types of errors APIs can respond with that should follow the standard HTTP error codes. Some errors may be best handled by displaying the returned error to the user, for example an issue with a manually inputted value, other issues may need to be detected and raised to the developers via email alerts or other messaging channels, such as API calls that are being made in background jobs, or errors that require developer action.
When developing an API integration, data consistency issues can arise due to various factors. It’s essential to identify and address these potential issues to ensure reliable and accurate data processing.

Concurrency issues – When multiple processes are simultaneously trying to update the same data it can result in the data being in an unexpected state. Database transactions should be used to ensure a group of transactions are either all applied, or the data rolls back to its original state.
Concurrency control can be used to check if a resource has been modified by another request before the changes are applied.
Data integrity issues – Validating data coming in from the API can ensure it is as expected before being processed. Database constraints can be used to ensure the data being stored is valid and consistent at the database level.

Testing and Deploying Your Custom Integration

Developing a comprehensive testing plan

A comprehensive testing plan should be created to ensure the HubSpot integration performs well and meets its requirements.
Functional Testing: There should already be clear understanding of the requirements for the integration, this should form the basis of the functional testing scenarios.

Performance Testing: load testing to assess performance under normal load conditions and stress testing to evaluate how the integration handles peaks in load and identify bottlenecks using tools such as LoadRunner or Gatling.
Security Testing: Test authentication and authorization to ensure secure access and prevention of unauthorised access. Verify data encryption methods are correctly implemented for data in transit and at rest e.g. HTTPS.

Error Handling and Recovery Testing: Test how the integration handles errors, such as network failures, API timeouts, or invalid data inputs. Validate retry and recovery mechanisms to ensure data integrity and system stability during transient errors.

Regression testing: Conduct regression tests to verify that new changes or updates do not adversely affect existing integration functionalities.
User Acceptance Testing (UAT): Ensure the stakeholders conduct UAT to validate the integration meets its requirements and usability. Define the process for collecting and implementing UAT feedback.

Monitoring and optimising performance post-deployment

Continuous Testing and Monitoring: Develop automated tests as part of the development, these tests should be run as part of the CI pipeline to detect issues. Use monitoring tools such as NewRelic to monitor the health of the integration and performance of the integration.

Deploying your integration in a staging environment

Deploying to a staging environment allows for the system to be tested in an environment that is not production. This allows testing by QA/UAT without concerns about messing up the system, sending emails to customers, testing performance without slowing down the live system.

Maintenance and Support

Any new integration will have end users that come across issues, whether they be bugs, a misunderstanding on what the integration is expected to do, a request for instructions etc. It’s important that the client has a clear mechanism for how to get support. HubSpot provides resources for creating support tickets either from the HubSpot UI or as an automated process from incoming emails. Using HubSpot ensures all support requests are in the same place, and can be assigned and tracked. HubSpots reporting and analytics tools can be used to gain insights and identify areas for improvement.

Technology changes, HubSpot will have new API endpoints added and old API endpoints deprecated over time, as will any other software used in the integration. New vulnerabilities will be discovered that require changes, and requirements for the integration may change,  therefore it’s important  to plan for ongoing maintenance. This will ensure the integration remains performant, reliable, secure and fit for purpose.

Future-Proofing Your Integration

HubSpot publish their product roadmap at https://www.hubspot.com/new which details their plans for their products and services going forward. They are not guarantees but are useful to help identify if the integration being developed is going to be supported going forward. Being aware of new features and how this could impact your integration, or allow you to plan how upcoming features could be added into the integration. They also publish a changelog https://developers.hubspot.com/changelog which contains updates about the APIs that are useful to developers. Keeping up to date with the announcements and taking action as required will ensure the integration remains compatible and secure.