How to implement webhooks on an existing application

New Member

I have an existing application that we use for company, contact, and engagement api access and it is working beautifully.

I am trying to add webhook functionality and having some difficulty. The accounts we are using are all Marketing Enterprise accounts and should have sufficient permission.

From the documentation, I cannot figure out what additional scopes I need to use. I authenticate with Oauth2 and complete the handshake correctly. I can then use all the necessary contacts, companies, engagements urls. I cannot use the webhooks urls because it returns it returns a "does not have proper permissions"

Can you please let me know what shortcoming I have? Is it permission scopes, application scopes, some other nuance? If you could kindly show me some documentation that helps and exiting application add webhooks, that would be great.

URL that fails: (with the necessary, correct Header Authorization: Bearer...)

I even used this in a REST tester and the header works when performing a call like:

Response body when trying to retrieve webhooks:

"status": "error",
"message": "This oauth-token (C...partially...removed...WkuazUJ1_) does not have proper permissions! (requires all of [developers-access])",
"correlationId": "c4647201-5764-471a-aa64-054bd867e303",
"requestId": "adc0836b9505173cf61bb674d52562e1"

5 Replies 5
Regular Contributor

Hi HubSpot app support team -- The problem that bobsmith0 reported is holding us up from implementing webhooks. Can someone from HubSpot please take a look at the note, and please let us know what gotchas to look out for? Here is some additional info to add to the previous note from our developer:

Hubid: 2705150
App name: Obtest

Thank you -- the webhooks functionality could be great, but we need to get it working. Thank you.

Vik Chaudhary
CEO | Dossier
A: 69 Dorman Ave, San Francisco, CA 94112

Community Manager

Hi @BobSmith0 & @vikchaudhary,

That error occurs when you're making requests using authentication from a Marketing/CRM portal (e.g. a test portal or a customer's portal) instead of authentication from your developer portal (e.g. you developer hapikey). If you're making requests to change/manage your webhook settings, you need to use your developer hapikey, not the OAuth tokens from test/customer portals.

Additionally, you can manage all webhook subscription details in your developer portal, so you don't need to use the API to manage your webhook settings (unless you want to). Check out the Webhook API docs again for some more details on subscribing to object notifications:

New Member

Thank you for your comprehensive reply. The use of the hapikey was the single line-item that I overlooked.

Now, using the hapikey as a passed query parameter, I have my webhook working.

I appreciate your reply.


On a side note, it does appear that a 200 return code I generate from the webhook payload also requires the X-HubSpot-Signature to be echoed back to HubSpot. This may not be clear in the documentation.

Community Manager

Hi @BobSmith0,

Glad to hear things are up and running! I'll check out the Webhook API docs and see if I can clarify the X-HubSpot-Signature bit.

New Member

Hi Guys,

I am facing issue while running webhook and they getting failed with error :- Webhook attempt failed due to an unrecognized error.