Skip to main content

​
HMAC Signature

HMAC (Hash-based Message Authentication Code) is a method used to authenticate a message using a shared secret and a hash function. It allows our clients to verify that the received webhook is from a trusted source (Deck) and that the information wasn’t tampered with, in which case the signature won’t match the shared secret. We use SHA-256, so trying to verify the hash with anything else will not work.

​
Why HMAC matters

HMAC adds an extra layer of protection to your webhooks by making sure that:
  • You can detect tampering – If the message is altered in transit, its signature won’t match.
  • Only trusted senders can sign messages – A valid signature can only be generated with the shared secret key.
  • Replay attacks are blocked – Including a timestamp or nonce prevents attackers from resending old messages.
  • Collisions are highly unlikely – Strong cryptographic hash functions make it extremely rare for two different messages to produce the same signature.

​
Where it is

An HMAC key is generated automatically when creating an account. To access it, go to your Dashboard and click on “API Keys” from the left menu. Click on “Security” and you will see your HMAC Key on top. The HMAC Key is the same for both Live and Sandbox environments.

​
How it will look in a Webhook

Any Webhook that will be sent to you will include an X-Signature header containing the HMAC hash of the payload. This signature can be validated using the aforementioned HMAC key.

​
Type of HMAC

The HMAC is in Base64. Note that Base64 is used to encode the raw binary output of the HMAC hash into a text-safe string so it can be sent via HTTP headers or stored easily. HMAC is not used to encrypt the rest of the information passed through the webhook, but its presence does not affect the encryption already in place.

​
Code to verify the HMAC

To verify that the HMAC received matches the one for your Team, you can use the following code examples. 
const crypto = require("crypto");

// Provided Base64-encoded secret
const secretBase64 = <<YOUR_DECK_WEBHOOK_SECRET_FROM_DASHBOARD>>;

// JSON body payload as a raw string (must match byte-for-byte) - This is AN EXAMPLE Webhook Event Body
const body = `{"link_token":"link-sandbox-77bd1897-b21b-4eb8-fca6-08dda362f7ed","public_token":"public-sandbox-b7500d0c-920d-46cf-44eb-08dda3634c66","webhook_type":"Link","webhook_code":"ConnectionCreated","environment":"Sandbox"}`;

// Decode the Base64 secret into a raw byte buffer
const key = Buffer.from(secretBase64, "base64");

// Create the HMAC hash
const hmac = crypto.createHmac("sha256", key);
hmac.update(body);
const computedSignature = hmac.digest("base64");

// Output
console.log("Expected Signature:", <<X_SIGNATURE_FROM_HEADER>>);
console.log("Computed Signature:", computedSignature);
Make sure that the Expected Signature and Computed Signature match.
⌘I