Instamojo creates a list of all values from the key-value pairs that we send in the POST request and sort them in the order of their keys alphabetically. We then concatenate all these values together, separated by a pipe (|) character. We then use the HMAC-SHA1 algorithm to generate the signature. The HMAC key for the signature generation is the secret salt from the user's profile. (You will find the salt at instamojo.com/developers if you are logged in)
How is the Message Authentication Code useful and do I need to use it?
The Message Authentication Code for the payload is what you can use to verify that the POST request is indeed sent by Instamojo, versus someone else trying to impersonate Instamojo and/or gain access to your data/systems.
You don't strictly need to use it since the data is sent in plain text, and therefore readable without verifying the MAC, it is a good idea to verify the MAC to ensure the integrity and authenticity of the POST request.
In short, using MAC is optional, but recommended as a security feature.
Here is the procedure for verifying MAC.
If d is a set of key-value pairs that corresponds to the POST request (Eg: d = {"foo": 1, "bar": 2, "baz": 3, "mac": 4})
- From d, remove the key-value pair that corresponds to the message authentication code (its key is "mac"). (Eg: new_d = {'foo': 1, 'bar': 2, 'baz': 3})
- Prepare a list of all values from the set d, ordered alphabetically by their keys in lower case. Eg: [2, 3, 1] (since the alphabetical order of the keys is: "bar", "baz" and "foo"))
- Concatenate all the items from this list into one string, with each item separated from the other with a pipe ('|'). (Eg: "2|3|1")
- Use the HMAC-SHA1 algorithm to generate a message authentication code using the above string as the message and the secret given to you by Instamojo as the salt. (Most programming languages have readymade libraries that implement HMAC-SHA1).
- Compare the message authentication code that you've derived using the above steps with the code you received from Instamojo (which was removed from d in step 1 above). If the strings are the same, consider the message verified.
Sample codes in Python and PHP can be found here: Webhook URL In PHP/Python