When it comes to using an API, security is essential for having control over who can access your service. At the same time, the integrity of a service’s security should never depend on a server session — each request made to an API must attach some form of credentials that the server validates.
What is HMAC?
The HMAC algorithm stands for Hashed or Hash-based Message Authentication Code that is acquired by executing a cryptographic hash function on the data to be authenticated and a secret shared key.
HMAC is a great defense against cryptanalysis attacks as it uses the Hashing concept twice. HMAC utilizes the benefits of both Hashing and MAC and thus is more secure than any other authentication code.
How does HMAC work?
HMAC authentication is a security mechanism used by public APIs that is relatively easy to deploy. The client or application that wants access to a service will need an API Key and a Secret Key from the service owner.
These keys are usually randomly generated strings given to a client beforehand. API Keys are unique to each client/application. Both the client and server will hold the API Key and Secret Key.
When the client makes a call to an API, the message content is hashed using the client’s secret key to generate an HMAC signature. This value, along with the original message and the API Key, is then passed to the server’s API.
On the server, the same process is repeated but this time using the private key stored on the server which is retrieved by the corresponding API key sent from the client. The generated HMAC signature is then compared against the one sent by the client. The request is authorized when both HMAC signatures match.
What are Webhooks?
Before we go deeper into how HMAC works in the signNow API, let’s quickly recap webhooks.
A webhook is used in web development as a method of altering the behavior of a web page or web application with custom callbacks. Simply put, webhooks are “user-defined HTTP callbacks” because they can be maintained, modified, and managed by third-party users and developers who may not be affiliated with the originating website or application.
Webhooks are usually triggered automatically by some event, such as pushing code to a repository or a comment being posted to a blog. When that event occurs, the source site or app makes an HTTP request to the URL configured for the webhook. Users can configure them to cause events on one site or app to invoke behavior on another.
Since webhooks are automated reactions to events that happen without human interference, it makes sense to be extra careful here. Webhooks are ideal for situations where you want to initiate an automated response to an event, such as document completion, and you want to create an automated flow around it.
Standard HTTP POST messages are easily forged. This has the potential to open a security vulnerability when using webhooks. And that’s the reason HMAC has become so popular among many security-aware developers and why the signNow API has the option to use it.
How HMAC works in signNow
Using the HMAC protocol, signNow provides API users with a shared private key to verify Webhook callbacks. Once the HMAC secret key is configured for an event subscription, a new header is included in every callback URL. This verifies that the message has been sent using signNow and has been delivered with an equal key.
How to set up HMAC?
To set up the HMAC mechanism for webhooks, API users need to set the secret_key parameter when creating a webhook event. This key is used to generate a specific signature header for each response from a triggered webhook in signNow.
Example 1: Create event subscription with HMAC secret key
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
curl -X POST \ https://api.signnow.com/api/v2/events \ -H 'Authorization = Bearer {{access_token}}' \ -H 'Content-Type = application/json' \ -d '{ "event":"document.fieldinvite.sent", "entity_id": "63fde884ad755149ff213563de654f9a61a1884c", "action":"callback", "attributes":{ "callback":"https://some.callback.url/", "use_tls_12":true, "integration_id":"b98fc00add6b43a606bc527c81eee741bf16a7d8", "docid_queryparam":true, "headers":{ "string_head":"test", "int_head":12, "bool_head":false, "float_head":12.24 }, "secret_key": "MySecretKey" // It enables HMAC security logic. } }' |
The signature header contains the original message body hashed with the HMAC key. To verify an event, the application validates the HMAC header using the provided secret_key and re-creates the original message.
Types of events
The event types include several groups such as:
- Document events (i.e. document.complete)
- User actions with documents (i.e. user.document.complete)
- Template events (i.e. template.copy)
- Field invite events (i.e. document.fieldinvite.create). A field invite is an invite to sign a document that contains at least one Signature field.
- Field invite events triggered by Document Owner (i.e. user.document.fieldinvite.create)
- Freeform invite events (i.e. document.freeform.create). A freeform invite is an invite to sign a document that has no fillable fields.
- Freeform invite events triggered by Document Owner (i.e. user.document.freeform.create)
- Document group events (i.e. user.document_group.create)
How to validate a webhook using HMAC
Once an event is created with the secret_key parameter, this secret key will be used to hash the webhook response body using the HMAC algorithm. The hash value will be sent in the X-SignNow-Signature HTTP header with each callback.
When the callback is received at your servers, you can use the secret_key to compute the HMAC hash value of the callback payload and compare it against the HMAC hash value in the X-SignNow-Signature HTTP header to verify that the request was sent by signNow.
Example 2: Verification of the HMAC hash
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
<?php class HMAC_Service { /* * Compute HMAC hash * Useful reference: https://www.php.net/manual/en/function.hash-hmac.php */ public static function ComputeHash($secret,$payload) { $hexHash = hash_hmac('sha256',$payload,utf8_encode($secret)); $base64Hash = base64_encode(hex2bin($hexHash)); return $base64Hash; } public static function HashIsValid($secret,$payload,$verify) { return hash_equals($verify, self::ComputeHash($secret,$payload)); } } ?> |
For more information on HMAC security, please see the signNow Documentation.
