topic Re: Introducing version 3 of Webhook signatures in Developer Announcements

Introducing version 3 of Webhook signatures

zwolfson — Mon, 25 Oct 2021 16:47:29 GMT

In order to help protect our partners and customers, HubSpot signs outgoing requests (such as those for webhooks or CRM cards) so that you can verify that the request did actually come from HubSpot. Following the latest security best-practices, we are adding two new headers to outgoing HubSpot requests to OAuth Apps - X-HubSpot-Signature-v3 and X-HubSpot-Request-Timestamp. Prior versions of the X-HubSpot-Signature header will continue to be included for backward compatibility. OAuth Apps can use the request signature to verify whether received requests are actually from HubSpot.

What’s happening

We are adding two new headers to outgoing requests: X-HubSpot-Signature-v3, X-HubSpot-Request-Timestamp.

To verify the signature, developers will need to perform the following steps:

Reject the request if the timestamp is older than 5 minutes.
Create a utf-8 encoded string that concatenates together the following: requestMethod + requestUri + requestBody + timestamp. The timestamp is provided by the new X-HubSpot-Request-Timestamp header.
Create an HMAC SHA-256 hash of the resulting string using the application secret as the secret for the HMAC SHA-256 function.
Base64 encode the result of the HMAC function.
Compare the hash value to the signature. If they're equal then this request has been verified as originating from Hubspot. We recommend using constant-time string comparison to guard against timing attacks.

These new headers are available now.

If you have any questions or comments, please join the discussion here.

Re: Introducing version 3 of Webhook signatures

amit-hs — Thu, 04 Nov 2021 19:04:54 GMT

Hi @zwolfson

We're just now experiencing an issue with signature verifications for v2 requests starting 10:15am Pacific time today November 4th. All signature validation simply fails, with secrets that used to work until that point.

It looks like HubSpot's public API libraries (like this ruby client: https://github.com/HubSpot/hubspot-api-ruby/blob/master/lib/hubspot/helpers/webhooks_helper.rb#L19) are not ready for this rollout, are they?

Re: Introducing version 3 of Webhook signatures

PHuston — Thu, 04 Nov 2021 19:05:10 GMT

@zwolfson despite not opting into the v3 signature validation described in your post, our signature validation suddenly broke at 10:15am PT this morning. Your statement around ensuring backwards compatibility does not seem to be accurate in our experience.

Could you please confirm whether this rollout is progressing as intended? For reference, there seem to be other users experiencing the same problem: https://community.hubspot.com/t5/APIs-Integrations/Incorrect-X-Hubspot-Signature-in-CRM-extension-s-requests/td-p/520140

If it is indeed true that this was rolled out without actual backwards compatibility, I would consider this to be a major breach of trust.

Thank you

Re: Introducing version 3 of Webhook signatures

zwolfson — Thu, 04 Nov 2021 19:52:37 GMT

Hi @PHuston and @amit-hs

There was an issue unrelated to this addition that affected the v2 version of webhook signatures. That issue should now be resolved.

Sorry for the errors caused by this issue.

Let us know if you have any other questions.

Thanks,
Zack

Re: Introducing version 3 of Webhook signatures

amit-hs — Fri, 05 Nov 2021 16:53:53 GMT

Thanks for the clarity Zack!

Re: Introducing version 3 of Webhook signatures

ajchennai — Sat, 18 Dec 2021 05:13:56 GMT

@zwolfson Webhook Form Submisssion signature verification fails, We are using rawBody for generate source string

Signature Version: v2

import * as crypto from 'crypto'; const signature = req.headers['x-hubspot-signature']; const body = req['rawBody']; const method = 'POST'; const secret = 'XXXX'; // Client secret const url = this.configService.get<string>('APP_URL') + req.originalUrl; const sourceStr = secret + method + url + body; const hash = crypto.createHash('sha256').update(sourceStr).digest('hex'); console.log(`${signature} === ${hash}`);

This was working when payload is small size of json, Fails on Form submission webhook. The form submission webhook payload its too large. Also it's very strange to debug this issue.

Re: Introducing version 3 of Webhook signatures

JJolly37 — Thu, 30 Dec 2021 11:46:38 GMT

@zwolfson regardless of not selecting into the v3 signature approval depicted in your post, our unmistakable approval out of nowhere broke at 10:15am PT today. Your articulation around guaranteeing in reverse similarity doesn't appear to be precise as far as we can tell.

Could you kindly affirm whether this rollout is advancing as planned? For reference, there appear to be different clients encountering a similar issue: https://community.hubspot.com/t5/APIs-Integrations/Incorrect-X-Hubspot-Signature-in-CRM-augmentation s-...

Assuming it is for sure a fact that this was carried out without real in reverse similarity, I would believe this to be a significant break of trust.

Much obliged to you

Re: Introducing version 3 of Webhook signatures

AChen4 — Thu, 27 Jan 2022 08:15:41 GMT

Hi, @zwolfson

I'm still trying to wrap my head around on how to concatinate the string correctly. I wish there's an example in the doc for us to confirm that our code is correct.

By any chance, does anyone has a php working sample? I kinda have this, but I can never generate the same signature as the header. Not sure what i'm doing wrong. Thought V3 is suppose to be more securied, but so hard to get it right.

// Create a utf-8 encoded string that concatenates together the following: requestMethod + requestUri + requestBody + timestamp. The timestamp is provided by the new X-HubSpot-Request-Timestamp header. $request_method = $_SERVER['REQUEST_METHOD']; $request_uri = $_SERVER['SCRIPT_URI']; $request_body = file_get_contents('php://input'); $request_timestamp = $_SERVER['HTTP_X_HUBSPOT_REQUEST_TIMESTAMP']; $string = utf8_encode("{$request_method}{$request_uri}{$request_body}{$request_timestamp}"); // Create an HMAC SHA-256 hash of the resulting string using the application secret as the secret for the HMAC SHA-256 function. $hash = hash_hmac('sha256', $string, HUBSPOT_APP_SECRET); // Base64 encode the result of the HMAC function. $encoded = base64_encode($hash); // Compare the hash value to the signature. If they're equal then this request has been verified as originating from Hubspot. We recommend using constant-time string comparison to guard against timing attacks. var_dump(hash_equals($_SERVER['HTTP_X_HUBSPOT_SIGNATURE_V3'], $encoded));

Thanks.

Re: Introducing version 3 of Webhook signatures

RSheladiya — Tue, 22 Feb 2022 18:08:19 GMT

I am working on X-Hubspot-Signature-V3 validation using below c# code but i am not getting correct hash value. can anyone suggest working c# code sample?

HttpContext.Request.Headers.TryGetValue("X-Hubspot-Request-Timestamp", out StringValues timeStamp );
HttpContext.Request.Headers.TryGetValue("X-Hubspot-Signature-V3", out StringValues v3);
var validRequest = false;
using (var stream = new StreamReader(HttpContext.Request.Body))
{
var body = await stream.ReadToEndAsync();
var method = HttpContext.Request.Method;
var requestUri = $"{Request.Scheme}://{Request.Host.Value}/";
HMACSHA256 hashObject = new HMACSHA256(Encoding.UTF8.GetBytes("screat"));
var data = string.Concat(method, requestUri, body, timeStamp);
byte[] utf = Encoding.UTF8.GetBytes(data);
var signatureV3 = hashObject.ComputeHash(Encoding.UTF8.GetBytes(data));
var encodedSignature = Convert.ToBase64String(signatureV3);
if (v3.Equals(encodedSignature))
{
validRequest = true;
}

}

Re: Introducing version 3 of Webhook signatures

amit-hs — Thu, 03 Mar 2022 12:47:01 GMT

Hi @AChen4 & @RSheladiya .... we're you able to eventually get past the probem and successfully create a working payload signature? We're considering a move to v3, and just want to ensure that the path is worthwhile. Do you have working pseudo-solutions to share? Thanks.

Re: Introducing version 3 of Webhook signatures

AChen4 — Thu, 03 Mar 2022 16:26:28 GMT

@amit-hs no, I'm still using v2. I can never get v3 to work.

Re: Introducing version 3 of Webhook signatures

RSheladiya — Fri, 04 Mar 2022 20:28:00 GMT

nevermind, I have figure it out.

it requies to user full uri

Re: Introducing version 3 of Webhook signatures

amit-hs — Mon, 07 Mar 2022 00:12:14 GMT

Nice! Do you mean this line should look different?

var requestUri = $"{Request.Scheme}://{Request.Host.Value}/";

Just so this is more helpful to other people coming here for a solution, could you post what the actual working code looks like?

Re: Introducing version 3 of Webhook signatures

liuyun — Fri, 18 Mar 2022 03:30:58 GMT

Hi @zwolfson, I don't find any way to specify the Signature Version(like v3), and now I find the webhook from hubspot is just v1, do I need to implement the three version verify method according to the version in

X-HubSpot-Signature-Version

looking forward to your reply, thx.

Re: Introducing version 3 of Webhook signatures

GPhillips9 — Fri, 25 Mar 2022 21:47:15 GMT

I'm experiencing issues validating the request. Here's my code, what am I getting wrong here? Please note the _fullWebHookUrl is the entire path (b692-98-231-78-177.ngrok.io/api/v1/HubSpotWebhooks/PostNotification)

Thanks for the help, I'm pretty well frustrated at this point.

private bool ValidateRequest(HttpRequest httpRequest, dynamic requestBody)
{
httpRequest.Headers.TryGetValue("X-Hubspot-Request-Timestamp", out var timeStamp);
httpRequest.Headers.TryGetValue("X-Hubspot-Signature-V3", out var v3);

HMACSHA256 hashObject = new(Encoding.UTF8.GetBytes(_appSecret));

var data = string.Concat(httpRequest.Method, _fullWebhookUrl, requestBody, timeStamp);
byte[] utf = Encoding.UTF8.GetBytes(data);

var signatureV3 = hashObject.ComputeHash(utf);
var encodedSignature = Convert.ToBase64String(signatureV3);

bool validRequest = v3.Equals(encodedSignature);
return validRequest;
}

Re: Introducing version 3 of Webhook signatures

mynameiskyleok — Wed, 30 Mar 2022 16:00:16 GMT

Make sure you include the protocol in your _fullWebHookUrl (e.g., https:// or http://)

Re: Introducing version 3 of Webhook signatures

GPhillips9 — Wed, 30 Mar 2022 16:50:08 GMT

Yes good point I do include it and still no dice...do you have it working?

Re: Introducing version 3 of Webhook signatures

mynameiskyleok — Wed, 30 Mar 2022 18:37:38 GMT

Sorry, that was the first thing that stood out to me. I'm not familiar with .NET but your logic looks correct to me. I have it working in Node.js which I can clean up and post as an example here if that'd be helpful.

The string I'm concatening and hashing for a CRM card looks like:

GEThttps://XXX-XXX-XXX-XXX.ngrok.io/path/to/endpoint?userId=XXXXXXXX&userEmail=emailmaria@hubspot.com&associatedObjectId=1&associatedObjectType=CONTACT&portalId=XXXXXXXX1648664076585

Keep in mind, yours will look a little different depending on what's in the request body for your webhook POST and if any query string parameters are being passed. I have no request body for a CRM card GET request:

portalId=XXXXXXXX<the request body would go here if there was one>1648664076585

Re: Introducing version 3 of Webhook signatures

DLiebner — Thu, 28 Apr 2022 15:20:47 GMT

Could you share your working v2 signature validation code?

Re: Introducing version 3 of Webhook signatures

AChen4 — Fri, 29 Apr 2022 00:25:53 GMT

@DLiebner

It'd be something like this

<?php $request_body = file_get_contents('php://input'); $hash = hash('sha256', HUBSPOT_APP_SECRET . $request_body); $valid = hash_equals($_SERVER['HUBSPOT_SIGNATURE'], $hash);