How to implement Webhooks in HubSpot, and how do they differ from an API?

[jackcoldrick]

HubSpot provides a number of different APIs and in addition to that we also offer the option of leveraging webhooks. This post discusses this in more detail and also elaborates on different methods of implementation. You can learn more about how that in this video I recorded. 

The key difference is that with an API request you are proactively "requesting" information from the system. This may not be required as the data may not have changed since your last request and may not be the most efficient use of your call limit. With a webhook on the other hand you are notified by the system as soon as the data changes without having to continually make API requests. Within HubSpot we have a few ways to use webhooks.

Here is a diagram highlighting the general differences. Notice how with an API we continually make requests despite the data never changing. With a webhook we simply tell the server once to let us know if something happens:

As mentioned you can achieve this in a variety of ways within HubSpot. I've broken them down in more detail below. Each have different use cases, strengths and weaknesses so it's important to qualify in more detail to ensure you know what to position/recommend.

1) Webhooks API: Free and up

This involves setting up an app and subscribing to various events occurring in any portal that your app is installed. Events include Contact, Company and Deal creation, deletions and property updates. The drawback to this is that it doesn't support Ticket objects. The major advantage is that it's lightweight and easy to setup. An example of the payload can be found here. More information on our Webhooks API can be found in our developer documentation.

2) Workflow Extensions API: Marketing Pro and up

This can only be used in contact based workflows. The big advantage is that it lets you customize the payload you wish to send to your webhook URL which makes things easier for your development team to process. It's also much more user friendly for the marketing team who are creating workflows. The big limitation is that it's only usable in Contact workflows (although there are plans to extend this to other types of workflow in the future). An example of the payload can be found here. More information on the workflow extensions API can be found in our developer documentation.

3) Workflow/Bot Webhook Action: Enterprise only

This can be used in all workflows namely Contact, Company, Deal, Ticket and Quote and/or Bot. HubSpot will post all of the object data to the webhook URL. There is no option to customize the payload. The advantage is that you can leverage it in all workflows. An example of the payload can be found here, More information on using the webhook action in a workflow can be found in our developer documentation. Information on using workflows in bots can be found here. 

The analogy I like to use is that imagine you have a friend you continually text asking when they're having a party (API request). Every time they respond with the same answer... No. So instead you tell your friend once to simply notify you when they're having a party (Webhook) so you don't have to keep texting them.

If you've any questions at all please do not hesitate to leave a comment below. Alternatively check out this video where I walk through all of the above.

[JessicaH]

Thanks for sharing this @jackcoldrick! 

[nsullivan]

I like the idea of using webhooks, I currently am building an application that integrates Hubspot, and it appears that I don't have access to webhooks on my developer account. Is there a way I can get those enabled in order to build this application?

[jackcoldrick]

Hey @nsullivan,

This should already be available as standard from a developer portal. You manage the webhooks from an app level in your developer portal. So providing you have setup a developer portal via the "Create developer account" option here you should be then able to create apps within the account.

Every app will have a "Webhook" card that looks something like the below:

You can define the webhook URL that HubSpot will send data to and the various subscriptions you wish to listen for. 

Hope this helps and if you are seeing something different let me know!

Jack

[nsullivan]

I see what you're saying. I was hoping to be able to use the workflow function of Hubspot. This would be so when a deal is closed won we could trigger a webhook to sync that record to the financial system.

[jackcoldrick]

Hey @nsullivan, 

Thanks for confirming! So that functionality (trigger a webhook action) is exclusive to portals with an Enterprise subscription, more information here. 

Having said that if you're just looking to explore/create an integration that you intend to use in other enterprise portals (not necessarily that one) perhaps, you could create a test account from a developer portal. That comes equipped with Developer edition Marketing, Sales and Service Hub. So you'd be able to utilize that functionality.

If that is not the case and upgrading to enterprise isn't an option (which I completely understand and not suggesting you do!) we are working on extending the functionality of the workflow extension API across all object type workflows. Right now it's only supported in contact workflows but available on Professional. The only real difference is that you customize the payload vs the webhook action which sends EVERYTHING to the webhook URL. I can't share specific dates in terms of ETAs but we're actively working on this at present and should solve for this type of problem.

Hope this helps,

Jack

[nsullivan]

I created a new one and it has webhooks enabled, but it appears that this older one (the one that has the integration already connected to) is downgraded to a lower edition.

Here is the ID: 6301943

Is it possible to upgrade that one to the higher edition so I don't have to rebuild the integration?

[jackcoldrick]

Hi @nsullivan we can certainly upgrade a PRO portal to ENT license but it will involve having a conversation with your account manager and there may be quite a jump in price. Is there anyone you've conversed with prior to purchasing HubSpot? This would be the best channel as I'm honestly not the best resource for this.

[nsullivan]

I'm only talking about my Developer Box like you had mentioned earlier. I have a developer box with an integration built in order to demo to clients wanting the hubspot integration. It used to be an ENT developer box and I was using webhooks to call out to my application. It has since been downgraded to a pro, and we are no longer able to use the webhook feature. 

I was hoping to upgrade the developer box back to the ENT so we could continue demo-ing our integration to Hubspot customers. We are not hubspot customers, we just build integrations between hubspot and other systems.

[jackcoldrick]

Hey @nsullivan,

Got ya, sorry for confusion thats crystal clear now. Ok, I've taken a look and it seems as though a Sales Pro trial was added to the account on May 18 which can cause scoping issues and basically downgrades the portal. I've just flagged issue with team on my end and we'll work to revert this for you. I'll post back as soon as I've an update. 

Thanks,

Jack

[nsullivan]

Gotcha, that was a colleague of mine. Thank you for your help!

[Harpal]

Hi, I am trying to use the "Trigger a webhook" bot action in a Chatflow to integrate it with an external bot which will use NLP and have other functionalities. I want to respond with a message in the webhook response. However in HubSpot documentation for working with bots here - it only shows an "Example response payload" with "botMessage" field as null.

So apart from a simple text message as a "botMessage", are there other fields that are supported for a webhook response? I have tried "quickReplies" and it works. Would be nice to have a documentation with all the supported fields.

Also the external bot supports Quick Replies that open a Url on click, sending and receiving images/files, and also sending rich cards. Would like to know if any of these capabilities are supported for HubSpot bot, specially a QR that opens a Url link.

Thanks.

[Daan_K]

Hi Jack,

Great post. I was wondering how would you retreive the user who triggered the webhook? I have set the subscriptions up via the backend but whenever my webhook triggers a contact is updated I should authenticate the corresponding authenticated user to retreive those details am I right? It can't be that I should create a subscription for each user and retreive that by using the subscriptionId since there is alimit for 1000 subscriptions?

Love to hear how HubSpot would knot this all together 🙂 

[jackcoldrick]

Hi @Daan_K, thanks for the comment, and apologies for slight delay in responding. It's been a particuarly busy week!

Would you mind elaborating in a little more detail as to what you're trying to do? It's true that you can only have a total of 1000 subscriptions per app. The payload we send to the webhook URL contains the following:

{
"eventId": 3269308127
"subscriptionId": 236664
"portalId": 2990812
"appId": 214207
"occurredAt": 1596024572003
"subscriptionType": "contact.propertyChange"
"attemptNumber": 0
"objectId": 388951
"propertyName": "lifecyclestage"
"propertyValue": "customer"
"changeSource": "COMPANIES"
}

The parameters included in the above are outlined below:

• eventId : The unique ID of the event that triggered this notification.
• subscriptionId : The ID of the subscription that caused us to send you a notification of this event.
• portalId : The customer's portalId that this event came from.
• appId : The ID of your application. (In case you have multiple applications pointing to the same webhook URL.)
• occurredAt : When this event occurred, as a millisecond timestamp.
• subscriptionType : The type of event this notification is for. See the list of subscription types in the above section on "Subscription Types".
• attemptNumber : Which attempt this is to notify your service of this event (starting at 0). If your service times-out or throws an error as described in "Retries" below, we will attempt to send the notification to your service again.
• objectId : The ID of the object that was created/changed/deleted. For contacts this is the vid; for companies, the companyId; and for deals the dealId.
• propertyName : This is only sent when the notification is for a property change. This is the name of the property that was changed
• propertyValue : This is only sent when the notification is for a property change. This is the new value that was set for this property that triggered this notification.
• changeSource : The source of this change. Can be any of the change sources that you find on contact property histories.

The actual HubSpot user ID is not included within that payload. Generally what people will do is use the objectID to pull additional information if it's required. 

Happy to chat more on this just want to learn a little more on your use case. 

[Ac2]

Hi

I'm reading your post but have a question. I have enterprise, and I perform a webhook, I receive the hook, look up some information, and I have no idea where to PUT the data I need to return.

I can't find any documentation on this, what am I missing?

[Cienn13]

Thanks for such amazing and helping post.