Developer Announcements

zwolfson
HubSpot Employee
HubSpot Employee

Introducing version 3 of Webhook signatures

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. 

0 Upvotes
GPhillips9
Participant

Introducing version 3 of Webhook signatures

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;
}

0 Upvotes
mynameiskyleok
Member

Introducing version 3 of Webhook signatures

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

GPhillips9
Participant

Introducing version 3 of Webhook signatures

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

GPhillips9_0-1648659030507.png

 

0 Upvotes
mynameiskyleok
Member

Introducing version 3 of Webhook signatures

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

 

0 Upvotes
liuyun
Member

Introducing version 3 of Webhook signatures

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.

0 Upvotes
RSheladiya
Member

Introducing version 3 of Webhook signatures

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;
}

}

0 Upvotes
RSheladiya
Member

Introducing version 3 of Webhook signatures

nevermind, I have figure it out. 

it requies to user full uri

0 Upvotes
amit-hs
Participant

Introducing version 3 of Webhook signatures

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?

0 Upvotes
AChen4
Member

Introducing version 3 of Webhook signatures

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.

 

 

0 Upvotes
amit-hs
Participant

Introducing version 3 of Webhook signatures

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.

0 Upvotes
AChen4
Member

Introducing version 3 of Webhook signatures

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

0 Upvotes
DLiebner
Participant

Introducing version 3 of Webhook signatures

Could you share your working v2 signature validation code?

0 Upvotes
AChen4
Member

Introducing version 3 of Webhook signatures

@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);
DLiebner
Participant

Introducing version 3 of Webhook signatures

Thank you!

0 Upvotes
JJolly37
Member

Introducing version 3 of Webhook signatures

@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

0 Upvotes
ajchennai
Member

Introducing version 3 of Webhook signatures

@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.

 

0 Upvotes
amit-hs
Participant

Introducing version 3 of Webhook signatures

Thanks for the clarity Zack!

 

0 Upvotes
zwolfson
HubSpot Employee
HubSpot Employee

Introducing version 3 of Webhook signatures

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

0 Upvotes
PHuston
Participant

Introducing version 3 of Webhook signatures

@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-...

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

0 Upvotes
amit-hs
Participant

Introducing version 3 of Webhook signatures

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?

0 Upvotes