Introducing version 3 of Webhook signatures

[zwolfson]

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. 

[ntiyiso-rikhots]

Those who are still struggling, please see https://stackoverflow.com/a/79162879/5375297

[GPhillips9]

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

[GBonaventura]

I know I'm 2 years later, but anyway.

I did this and worked for me:

[HttpPost]
public async Task<IActionResult> Webhook()
{
    var res = await ValidateRequest(HttpContext);
    return Ok(res);
}

private async Task<bool> ValidateRequest(HttpContext httpContext)
{
    httpContext.Request.Headers.TryGetValue("X-Hubspot-Request-Timestamp", out var timeStamp);
    httpContext.Request.Headers.TryGetValue("X-Hubspot-Signature-V3", out var v3);
    
    var webHookUrl = $"{httpContext.Request.Scheme}://{httpContext.Request.Host}{httpContext.Request.Path}";
    var fullWebhookUrl = new Uri(webHookUrl).AbsoluteUri;

    HMACSHA256 hashObject = new(Encoding.UTF8.GetBytes(_appSecret));
    
    var payload = "";
    using (var reader = new StreamReader(httpContext.Request.Body, leaveOpen: true))
    {
        payload = await reader.ReadToEndAsync();
    }
    
    var data = string.Concat(httpContext.Request.Method, fullWebhookUrl, payload, timeStamp);
    var utf = Encoding.UTF8.GetBytes(data);

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

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

[mynameiskyleok]

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

[GPhillips9]

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

[mynameiskyleok]

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

[liuyun]

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.

[RSheladiya]

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

}

[RSheladiya]

nevermind, I have figure it out. 

it requies to user full uri

[amit-hs]

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?

[AChen4]

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.

[FTraina]

You forgot to emit the hash_hmac as raw binary.

Amend

$hash = hash_hmac('sha256', $string, HUBSPOT_APP_SECRET);

to

$hash = hash_hmac('sha256', $string, HUBSPOT_APP_SECRET, true);

[amit-hs]

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.

[AChen4]

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

[DLiebner]

Could you share your working v2 signature validation code?

[AChen4]

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

Thank you!

[JJolly37]

@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

[ajchennai]

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

[amit-hs]

Thanks for the clarity Zack!