HMAC Signature

What is HMAC?

HMAC stands for Hash-based Message Authentication Ccode and plays a crucial role in ensuring that the webhook is sent from verified sender.

What is a hash function?

Imagine a hash function as a magical machine that takes any kind of input, like a word, a sentence, or even a whole book, and transforms it into a fixed-size jumbled-up code. This code looks like a random string of letters and numbers. The interesting thing is that no matter how long or short the input is, the output (the code) will always be the same length.

If the input is changed even a little, like adding a single letter or changing a single word, the entire output code changes in a way that seems completely random. This makes hash functions really good for detecting any changes in the input.

Think of it like a fingerprint for data. Just like each person has a unique fingerprint, each piece of data has a unique hash code. And if someone tries to change even a small detail of the data, the hash code will change completely, just like a different person.

How is HMAC signature generated?

We use HMAC-SHA512 to generate the secret.

Why use HMAC signature?

Let’s say there are two parties involved: the sender and the receiver. Before they start exchanging webhooks, they get a chance to establish an exclusive secret between them. Now when they start exchanging webhooks, the receiver wants to ensure the integrity of the webhook. This is the reason the sender needs to include an authentication code with the message. If a message has been tampered with, the authentication code and the message won’t align and the receiver knows that the communication between the sender and receiver has been compromised.

Why is HTTPS along with Static IPs isn’t enough?

HTTPS gurantees encryption of messages so that no middleman forwarding the message can read it, but that doesn’t stop them from modifying the message.

Static IPs still needs some router in between to connect to the receiver. This router can potentially be malicious and tamper the message.

The solution: Use a combination of HTTPS, Static IPs from sender and HMAC signature.

What is zero downtime rotation?

Earlier we talked about sharing a secret between sender and receiver. In a scenario where it’s suspected that this secret is leaked, it becomes crucial to establish another secret. The trouble is that the sender might be sending webhooks continuously to receiver. If the sender directly changes the secret, the receiver might start failing, or if the receiver changes the secret, it will keep invalidating the webhooks even though they are valid. To handle this, the sender generates a new secret but keeps the old secret for a few days and generates the two HMAC signatures and sends them in the webhook headers. The receiver is supposed to iterate through the list of signatures and figure out if at least one of them is valid. The receiver has a few days to start using the new secret to validate since the sender will eventually stop sending two signatures.

What if there was no zero downtime rotation?

Then the sender and the receiver have to change the secret and do a deployment at the same time. For a high volume sender, this is impossible to achieve as even a few seconds difference can mean losing precious data and having inconsistencies.

Custom HMAC headers

By default all projects will send the X-Nirah-Signature header where in we can replace the word Nirah with any custom word. We offer this feature in the free tier itself during the time of project creation. It is difficult to upgrade this in future especially once the receiver has started depending on them.


  1. Securing Stream Ciphers - Computerphile
  2. Practical Cryptography for Developers
  3. MAC & HMAC by Christof Paar
  4. RFC2104: Keyed-Hashing for Message Authentication