# Introducing version 3 of Webhook signatures

**URL:** <https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895>\
**Category:** Developer Announcements\
**Tags:** api\
**Created:** [October 25, 2021, 4:47pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895 "2021-10-25T16:47:29Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![zwolfson](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/zwolfson/32/81360_2.png) [@zwolfson](https://community.hubspot.com/u/zwolfson)\
**Post date:** [October 25, 2021, 4:47pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/1 "2021-10-25T16:47:29Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![amit-hs](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/amit-hs/32/53612_2.png) [@amit-hs](https://community.hubspot.com/u/amit-hs)\
**Post date:** [November 4, 2021, 7:04pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/2 "2021-11-04T19:04:15Z")

</div>

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](https://github.com/HubSpot/hubspot-api-ruby/blob/master/lib/hubspot/helpers/webhooks_helper.rb#L19)) are not ready for this rollout, are they?

---

<div class="post-metadata">

**Author:** ![PHuston](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/phuston/32/18373_2.png) [@PHuston](https://community.hubspot.com/u/PHuston)\
**Post date:** [November 4, 2021, 7:05pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/3 "2021-11-04T19:05:10Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![zwolfson](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/zwolfson/32/81360_2.png) [@zwolfson](https://community.hubspot.com/u/zwolfson)\
**Post date:** [November 4, 2021, 7:52pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/4 "2021-11-04T19:52:37Z")

</div>

Hi @PHuston and @amit-hs

There was an [issue](https://status.hubspot.com/incidents/t9br2j17f3g3) 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

---

<div class="post-metadata">

**Author:** ![amit-hs](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/amit-hs/32/53612_2.png) [@amit-hs](https://community.hubspot.com/u/amit-hs)\
**Post date:** [November 5, 2021, 4:53pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/5 "2021-11-05T16:53:53Z")

</div>

Thanks for the clarity Zack!

---

<div class="post-metadata">

**Author:** ![ajchennai](https://avatars.discourse-cdn.com/v4/letter/a/50afbb/32.png) [@ajchennai](https://community.hubspot.com/u/ajchennai)\
**Post date:** [December 18, 2021, 5:13am UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/6 "2021-12-18T05:13:56Z")

</div>

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

Signature Version: v2

```lia-code-sample
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.

---

<div class="post-metadata">

**Author:** ![JJolly37](https://avatars.discourse-cdn.com/v4/letter/j/ad7895/32.png) [@JJolly37](https://community.hubspot.com/u/JJolly37)\
**Post date:** [December 30, 2021, 11:46am UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/7 "2021-12-30T11:46:38Z")

</div>

@zwolfson regardless of not selecting into the v3 signature approval depicted in your [

post

]([Hotel East Houston - Swimming Pool, Bed & Breakfast - La Quinta](https://laquintahouston.com/about-us/)), 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](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

---

<div class="post-metadata">

**Author:** ![AChen4](https://avatars.discourse-cdn.com/v4/letter/a/dbc845/32.png) [@AChen4](https://community.hubspot.com/u/AChen4)\
**Post date:** [January 27, 2022, 8:13am UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/8 "2022-01-27T08:13:20Z")

</div>

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.

```lia-code-sample
// 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.

---

<div class="post-metadata">

**Author:** ![amit-hs](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/amit-hs/32/53612_2.png) [@amit-hs](https://community.hubspot.com/u/amit-hs)\
**Post date:** [March 3, 2022, 12:47pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/9 "2022-03-03T12:47:01Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![AChen4](https://avatars.discourse-cdn.com/v4/letter/a/dbc845/32.png) [@AChen4](https://community.hubspot.com/u/AChen4)\
**Post date:** [March 3, 2022, 4:26pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/10 "2022-03-03T16:26:28Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![DLiebner](https://avatars.discourse-cdn.com/v4/letter/d/a698b9/32.png) [@DLiebner](https://community.hubspot.com/u/DLiebner)\
**Post date:** [April 28, 2022, 3:20pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/11 "2022-04-28T15:20:47Z")

</div>

Could you share your working v2 signature validation code?

---

<div class="post-metadata">

**Author:** ![AChen4](https://avatars.discourse-cdn.com/v4/letter/a/dbc845/32.png) [@AChen4](https://community.hubspot.com/u/AChen4)\
**Post date:** [April 29, 2022, 12:25am UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/12 "2022-04-29T00:25:53Z")

</div>

@DLiebner

It’d be something like this

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

```

---

<div class="post-metadata">

**Author:** ![DLiebner](https://avatars.discourse-cdn.com/v4/letter/d/a698b9/32.png) [@DLiebner](https://community.hubspot.com/u/DLiebner)\
**Post date:** [April 29, 2022, 1:32am UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/13 "2022-04-29T01:32:20Z")

</div>

Thank you!

---

<div class="post-metadata">

**Author:** ![FTraina](https://avatars.discourse-cdn.com/v4/letter/f/5fc32e/32.png) [@FTraina](https://community.hubspot.com/u/FTraina)\
**Post date:** [May 24, 2022, 3:10pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/14 "2022-05-24T15:10:10Z")

</div>

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);`

---

<div class="post-metadata">

**Author:** ![RSheladiya](https://avatars.discourse-cdn.com/v4/letter/r/a698b9/32.png) [@RSheladiya](https://community.hubspot.com/u/RSheladiya)\
**Post date:** [February 22, 2022, 6:08pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/15 "2022-02-22T18:08:19Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![RSheladiya](https://avatars.discourse-cdn.com/v4/letter/r/a698b9/32.png) [@RSheladiya](https://community.hubspot.com/u/RSheladiya)\
**Post date:** [March 4, 2022, 8:28pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/16 "2022-03-04T20:28:00Z")

</div>

nevermind, I have figure it out.

it requies to user full uri

---

<div class="post-metadata">

**Author:** ![amit-hs](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/amit-hs/32/53612_2.png) [@amit-hs](https://community.hubspot.com/u/amit-hs)\
**Post date:** [March 7, 2022, 12:12am UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/17 "2022-03-07T00:12:14Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![liuyun](https://avatars.discourse-cdn.com/v4/letter/l/a8b319/32.png) [@liuyun](https://community.hubspot.com/u/liuyun)\
**Post date:** [March 18, 2022, 3:30am UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/18 "2022-03-18T03:30:58Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![GPhillips9](https://avatars.discourse-cdn.com/v4/letter/g/53a042/32.png) [@GPhillips9](https://community.hubspot.com/u/GPhillips9)\
**Post date:** [March 25, 2022, 9:47pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/19 "2022-03-25T21:47:15Z")

</div>

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](http://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;  
}

---

<div class="post-metadata">

**Author:** ![mynameiskyleok](https://d10pqhm3lwygmk.cloudfront.net/user_avatar/community.hubspot.com/mynameiskyleok/32/90272_2.png) [@mynameiskyleok](https://community.hubspot.com/u/mynameiskyleok)\
**Post date:** [March 30, 2022, 4:00pm UTC](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895/20 "2022-03-30T16:00:16Z")

</div>

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

[Next page](https://community.hubspot.com/t/introducing-version-3-of-webhook-signatures/45895.md?page=2)