InsCipher strongly recommends that all customers implementing webhooks employ industry-standard security measures to protect data in transit. We advise utilizing a digital signature called an HMAC, or Hash-based message authentication code, generated at the time of webhook creation, to authenticate incoming events. This practice safeguards your server against unauthorized or potentially malicious webhook notifications, ensuring the integrity and authenticity of all received data. The process of an HMAC being validated is a simple but highly secure process between sender and receiver:

• A secure secret key is generated by InsCipher.
• This secret is shared with your organization at the time of generation.
• When InsCipher sends the webhook request to your specified endpoint, the secret key is combined with the message content and run through a SHA-256 cryptographic hash function which produces a fixed-length HMAC.
• When receiving the request, the receiver is able to see both the original request and HMAC - which is sent in the request headers under the field X-HMAC-Signature. An example header value is provided below:
  X-HMAC-Signature: 9qf892ch4978cbq298dc423eaksgru28934cewichaw98vjw32e23trhl
• To verify the authenticity of the request, the receiver uses the same secret key and hash function to calculate their own HMAC.
• If the receiver's calculated HMAC matches the one sent in the request from InsCipher, it verifies that the message hasn't been tampered with during transition and that it was sent from the expected sender.

Considerations before getting started

Before you start verifying HMAC signatures, be advised that:

• This feature is available to Filing Agency Admins and Agency Admins
• If your HMAC secret is lost, you must create a new one from the UI.
• It is your responsibility to store your unique HMAC secret in a secure location and not to share it with anyone. We advise that only technical administrators in charge of both generating this key from the UI and storing it.

How to set up HMAC for your webhook endpoint

To start receiving webhooks that have been signed with HMAC, you can go to Connectivity Settings > HMAC Secret and click the Get new HMAC secret button. This automatically adds the 20-character generated secret key to your clipboard. Please immediately store this secret in a highly secure but easily accessible location.

Once you have this secret key, you will need to utilize it along with each individual webhook request body in a SHA-256 cryptographic hash function to create the HMAC. Compare the value output in your own function for each request to the value of the HMAC in the X-HMAC-Signature and ensure that it matches before fully verifying the request.

If you need help constructing your own solution for verifying HMAC signatures to start the testing process, please contact a member of the InsCipher technical team.