When is it best to use a Webhook vs. an API with HubSpot?

After reading the headline, you might be scratching your head, thinking, “Wait, isn’t a webhook an API?” Yes – it is! 

HubSpot offers several different APIs with different functionalities so that you can use HubSpot efficiently for your business needs. There are circumstances where it’s best to specifically use webhooks and others for which a different API is the better option.

When, for instance, your business reps need to be notified by the platform as soon as there is a data change, making multiple REST API requests can eat up your rate limits and create friction for your data process. This is one reason why webhooks are helpful!

I’ll explain more about webhooks and APIs in modern web development and when it’s best to use either with HubSpot.

Introduction to webhooks and APIs

In modern web development, webhooks and APIs are two methods that enable applications to communicate with each other. 

An API (Application Programming Interface) is a set of rules and standards that allows applications to talk to each other. APIs are often used to retrieve and send data to or from a server. For example, when you use a mobile app to check the weather, the app is most likely using an API to retrieve the current weather data from a server.

Webhooks allow apps to stay up-to-date with real-time information. Webhooks can also be called event-driven APIs and are typically used to provide other applications with real-time data. When an event happens within an app, it will send a message to a specified URL with the relevant data. A weather app might use a webhook to alert you when severe weather is in your area.

APIs and webhooks are essential tools for building applications that can communicate with each other and are two methods for integrating with HubSpot. Using these technologies, developers can create seamless experiences for end users—especially with the HubSpot CRM—by allowing different integrations to work together and share data.

Now, let’s learn more about how we can use webhooks and APIs with HubSpot and when it’s best to use each.

When to use an API with HubSpot

Most HubSpot APIs are REST APIs with HTTP features that enable you to interact with your data. When using these APIs with the HubSpot CRM, it’s best to use them when you need to retrieve specific data from the CRM or want to perform a particular action within the CRM. For example, you could use the API to retrieve a list of all the contacts in the CRM or to update a contact's information.

While webhooks are great for sending notifications when an event occurs, as mentioned earlier, an API is best when you need to access and manipulate data with HubSpot.

Here are a few examples of when you might want to use the HubSpot APIs vs. a webhook:

• Retrieve data from HubSpot, such as a list of objects. Then, you can use the appropriate API endpoint to request this data, which allows you to access and use the data in your app or integrate it with an external system.

• Update data in your HubSpot account, such as the stage of a deal or notes on a contact. You can use the relevant API endpoint to do this. This lets you modify the data in your HubSpot account in a programmatic way without needing to use the HubSpot UI.

• Create new data, such as a brand new company contact or deal. This can be done using the appropriate API endpoint, allowing you to automate data creation in HubSpot without manually entering data through the HubSpot UI.

The HubSpot APIs are necessary when you need to access or modify data in your HubSpot account from a technical point of view instead of receiving notifications about events like a webhook. 

How to use HubSpot APIs

When using HubSpot APIs, you need to make an HTTP request to the appropriate API endpoint. Depending on the particular API, language, and framework, the exact details will vary. However, as a general rule, this is how to use the HubSpot APIs.

HubSpot offers several different APIs for different purposes, so your first step is to figure out the API endpoint you want to use; Once you have the data from the API that suits your needs, you can use it in your application or integrate it with other systems.

Here are some helpful resources to help you jump-start your API journey with HubSpot and some necessary topics and tools that will help you along the way:

• API developer guides & resources
• HubSpot API reference documentation
• API usage guidelines

You can find more information on different HubSpot APIs in the HubSpot API documentation, which includes instructions and examples of making requests and processing API responses.

When to use a webhook with HubSpot

It is best to use a webhook with the HubSpot CRM when you need real-time communication or when you want to automatically trigger an action in another application based on a subscribed event that occurs in the CRM. 

Here are a few examples of when you might want to use a webhook with HubSpot:

• Integrate your HubSpot account with another application, such as your billing system or a similar service. This enables you to automate processes that sync your data between the different systems.

• Augment customer data, ensuring customers receive valuable data from your integration in a HubSpot workflow. This allows the customer to decide when and how your integration gets used in their accounts. You can do this with webhooks by triggering a custom action in your application when a specific event occurs.

• Send/sync data and receive real-time notifications with an integration to an external service, like Slack or Microsoft Teams, where you could receive alerts about conversations or messages in HubSpot. You can use a webhook to create a custom integration between HubSpot and a separate service.

Indeed, the notification aspect is one of the most important benefits of a webhook. However, webhooks are also excellent for integrating HubSpot with other systems and automating processes. 

How to use a webhook with HubSpot

When using webhooks with HubSpot, you can use them differently, depending on your specific needs and the type of data you send and receive. Here are the different ways you can use webhooks in HubSpot:

Using the Webhooks API

This approach using webhooks is lightweight and quick to set up using a HubSpot app and subscribing to events within any portal with access to your app. You subscribe by registering a URL in your app that can receive notifications when the specific events you’re subscribed to occur. 

Here is an example of how you might use the webhooks API in HubSpot to create a webhook subscription:

1. Determine the events you want to be notified about. For example, you might want to be notified when a deal closes.

   • Note: Selecting a limited data set is essential when determining which events you want to subscribe to. Often, developers will subscribe to all events or property updates for all CRM objects, which can overwhelm your system with updates.

2. Determine what data will be included and how to handle it best. The data method (POST) is used to send a request to your webhook URL and formatted with JSON, which is controlled by HubSpot.

3. Use the Webhooks API endpoint to create a new webhook subscription. You'll need to specify the events you'd like to be notified about, the URL that will receive the notifications, and the method and data format used.

Once your webhook subscription is created, your application will be notified whenever the specified events occur in HubSpot. You can then use the data from the webhook notification to perform any custom actions or integrations you have implemented in your application.

Using Webhook Actions in Workflows

This approach using HubSpot’s workflow tool enables you to create custom actions or an integration based on HubSpot workflow enrollment triggers. To use a webhook action in a workflow, customers need to connect your app, at which point your custom action shows up like any other workflow action. This action is created as part of a public app and then added to a workflow by a customer when they install it. This idea ensures that the customers control when data is sent to the integration. 

Therefore, as a developer building the app, you control which data or types of data are sent, including the format—but it’s the customer who determines how the workflow is triggered and where this custom action would go within the workflow. Using custom actions gives customers a native HubSpot experience with little effort on their end, while developers do most of the heavy lifting.

Here is an example of how you might use a webhook action in a HubSpot workflow:

1. Collaborate with the customer to determine the event, aka the enrollment criteria that will trigger the workflow. For example, the customer might want to trigger a workflow when a new contact is added to the HubSpot account. 

   • Note: This step doesn’t apply when you build the action itself. However, as the developer, you can provide suggestions for the workflow to help support customers using these custom actions. 

2. Create a webhook definition in your application to receive notifications when the specified event occurs in HubSpot. Within this definition, you will need to specify the following details:

   • How the action will look for the customer who added it to their workflow, and how it will provide options for formatting the data.
   • What data will be included and enable flexibility for the customer to include other data if needed when setting up the custom action.
     
     Ensuring these details before the action is sent to the integrator’s URL that will receive the notifications and data format will create the best experience for the customer.
3. Create a new workflow in HubSpot and add a webhook action to the workflow. Configure the webhook action to send a request to your webhook URL when the workflow is triggered.

Once your workflow is set up, it will be triggered whenever the event occurs in HubSpot. The webhook action sends a request to your webhook URL and your app, prompting the necessary actions or integration you implemented.

Conclusion

Typically, webhooks are better suited for scenarios that require real-time communication and automatic actions, while APIs are better suited for accessing and manipulating data within an application. It is essential to consider the specific requirements of your use case when deciding whether to use a webhook or an API with the HubSpot CRM.