APIs & Integrations

jackcoldrick
HubSpot Employee
HubSpot Employee

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

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:

 

webhook vs api.png

 

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: Operations Hub Professional 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.
Jack Coldrick
Solutions Engineer @ HubSpot
Add me on LinkedIn
29 Replies 29
Unmatched
Participant

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

Hey! I just wanted to make this thread aware of our new app, Hooked.

 

Hooked allows you to easily send a webhook through our app, with a subscription to Marketing, Sales, or Service Professional.

 

You can send via GET, POST, PATCH, PUT, or DELETE. Super easy to use, and free for up to 60 requests a month.

 

App store link here.

 

Cheers,
Matt from Unmatched

0 Upvotes
NSadot
Member

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

Nice video but there is no mention here on how to actually connect an account with the app. 

After I created the app in the developer account I copied the installation full url - it then prompt me to choose an account - I signed into it (live, produciton account) and granted access but I still don't see ANY webhooks. This part is not described anywhere, I posted a question and got no response and HS support is unable to answer why it's not working... Can you help with this? 

0 Upvotes
TZiesing
Contributor

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

@jackcoldrick Hi Jack, Thanks for providing this information. I would have an additional question: would a webhook request within a workflow require that an app is build in a developer account or can I simply use a private app id ?

My settings in the current workflow are: 

Authentication type: Include request signature in header

HubSpot App ID: xxxxxxx

Request body: "Customize request body"

and then I am listing all the properties.... 

 

Everything seems fine and in the action logs is says success: but when I click on the event message there appears: 

{"exception":"Bad POST data -- The API key not supplied","Status":400}

 

so I am wondering if the private app is not configured properly, if I have to build a new app via my developer account, if I have to append the api key or token in the urls or what else is going wronghere.... 

Any hint would be very much appreciated.  Thanks!

0 Upvotes
Eric_Goldman
Participant

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

We found this thread to be instructive as explored HubSpot Webhooks.

 

But sometimes, the Webhook API and Workflow feature still don't do the trick. Either you want to subscribed to a webhook for different kinds of events, or you can't create the kinds of re-enrollment events to make Workflows feasible.

 

We wrote up a quick blog post about how what to do in these situations:

 

https://blog.sequin.io/what-to-do-without-hubspot-webhooks

 

 

 

Unmatched
Participant

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

Hey Eric, I'd be keen to know what you think of Hooked, our new app with enhanced webhook functionality. Let me know?

0 Upvotes
martinc_henry
Member

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

Issues with webhook signature for payloads with emoji?

 

Hi! Not sure if i should open a new issue for this.

 

We've been using workflow webhooks with few issues but now on creating a new contact-based workflow we could not get the hash we calculated to match the signature we received. Now after trying with a different contact it matches. As i can't be 100 % sure on the way HubSpot actually generates the signature, it's difficult to debug the actual issue, but the only thing i can think of is that it treats certain characters like emojis differently.

 

Though i'm relieved our use case has worked, i'm worried future webhooks will fail because of a similar problem.

 

Just in case, i'll include our signature verification implementation:

 

```

const verifySignature = (req) => {
  const v2 = req.headers['X-HubSpot-Signature-Version'.toLowerCase()] === 'v2';
  const unhashed = `${process.env.HUBSPOT_CLIENT_SECRET}${
v2 ? req.method : ''
}${v2 ? `${process.env.TALENT_API_ORIGIN}${req.originalUrl}` : ''}${
Object.keys(req.body).length ? JSON.stringify(req.body) : ''
  }`;
  const hash = crypto.createHash('sha256').update(unhashed).digest('hex');
  const signature = req.headers['X-HubSpot-Signature'.toLowerCase()];
  return signature && hash === signature;
};

```

0 Upvotes
GReid5
Member

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


@martinc_henry wrote:

Issues with webhook signature for payloads with emoji?

 

Hi! Not sure if i should open a new issue for this.

 

We've been using workflow webhooks with few issues but now on creating a new contact-based workflow we could not get the hash we calculated to match the signature we received. Now after trying with a different contact it matches. As i can't be 100 % sure on the way HubSpot actually generates the signature, it's difficult to debug the actual issue, but the only thing i can think of is that it treats certain characters like emojis differently.

 

Though i'm relieved our use case has worked, i'm worried future webhooks will fail because of a similar problem.

 

Just in case, i'll include our site signature verification implementation:

 

```

const verifySignature = (req) => {
  const v2 = req.headers['X-HubSpot-Signature-Version'.toLowerCase()] === 'v2';
  const unhashed = `${process.env.HUBSPOT_CLIENT_SECRET}${
v2 ? req.method : ''
}${v2 ? `${process.env.TALENT_API_ORIGIN}${req.originalUrl}` : ''}${
Object.keys(req.body).length ? JSON.stringify(req.body) : ''
  }`;
  const hash = crypto.createHash('sha256').update(unhashed).digest('hex');
  const signature = req.headers['X-HubSpot-Signature'.toLowerCase()];
  return signature && hash === signature;
};

```


Got it but I am facing an issue in compiling I am facing an unknown issue. Please let me know if you have any best solution. Waiting for your best response. 

0 Upvotes
RMoffit
Member

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


@jackcoldrick wrote:

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:

 

webhook vs api.png

 

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: Operations Hub Professional 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 olansi luftreiniger where I walk through all of the above.

 Thanks for sharing the northell amazing stuff.  Many good luck for your help.

0 Upvotes
01470
Member

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

I'm just discussing my Developer Box like you had referenced before. I have a designer enclose with an incorporation constructed request to demo  to customers needing the hubspot mix. It used to be an ENT designer box and I was utilizing webhooks to shout to my application. It has since been minimized to an ace, and we are at this point not ready to utilize the webhook include.

I was wanting to redesign the designer box back to the ENT so we could proceed with demo-ing our combination to Hubspot clients. We are not hubspot clients, we simply assemble reconciliations among hubspot and different frameworks

0 Upvotes
alexair
Member

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

There is no website associated with Developer Portals. You can create a new test portal by clicking a link named "Test Portals" in the left hand sidebar. You will be able to test your app on live pages in each test portal.

0 Upvotes
mapletechn
Participant

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

I developed webhooks into my app, but still it does not receive notifications from my customers who installed the app.

What is the problem? Do they have to have an interprise account?

0 Upvotes
JJolly3
Member

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

I'm simply examining my Developer Box like you had referred to previously . I have a designer encase with  a coordination collected solicitation to demo to clients requiring the hubspot compromise. It used to be an ENT engineer box and I was using webhooks to yell to my application. It has since been limited to a star, and we are not, now prepared to use the webhook feature.

I was hoping to redesign the specialist box back to the ENT so we could continue with demo-ing our joining to Hubspot customers. We are not hubspot customers, we just amass blends among hubspot and various systems.

0 Upvotes
JJolly3
Member

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

I'm just discussing my Developer Box like you had referenced before . I have an engineer enclose with a coordination assembled request to demo to customers needing the hubspot reconciliation. It used to be an ENT engineer box and I was utilizing webhooks to shout to my application. It has since been minimized to a star, and we are not, at this point ready to utilize the webhook highlight.

I was expecting to overhaul the engineer box back to the ENT so we could proceed with demo-ing our joining to Hubspot clients. We are not hubspot clients, we simply assemble mixes among hubspot and different frameworks.

0 Upvotes
Daan_K
Member

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

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 🙂 

0 Upvotes
jackcoldrick
HubSpot Employee
HubSpot Employee

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

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. 

Jack Coldrick
Solutions Engineer @ HubSpot
Add me on LinkedIn
0 Upvotes
Ac2
Member

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

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?
0 Upvotes
Cienn13
Member

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

Thanks for such amazing and helping post.

0 Upvotes
Harpal
Member

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

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.

0 Upvotes
nsullivan
Member

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

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?

0 Upvotes
jackcoldrick
HubSpot Employee
HubSpot Employee

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

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:

 

Screen Shot 2020-07-24 at 1.30.10 PM.png

 

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

Jack Coldrick
Solutions Engineer @ HubSpot
Add me on LinkedIn