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.

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.
• You can work with InsCipher's team to send test data to your specified endpoint URL before going live, ensuring that you are able to validate the HMAC key in a staging environment before going live.

Steps in secret key generation and validation

The process of an HMAC being validated is a simple but highly secure process between sender and receiver consisting of the following steps:

1. Generate your Secret Key
   • The first step involves generating a cryptographically secure 20-character secret key from within the InsCipher portal.
   • For Filing Agency Admin users: Navigate to your username at top right ➡️Profile & Preferences ➡️ Connectivity Settings (bottom of page) and click Get New HMAC Secret.
     For Agency Admin users: Navigate to the left sidebar to Settings ➡️ Connectivity Settings and click Get New HMAC Secret.
   • This key has been copied to your clipboard. Please paste it in a secure location, as this key is only shared once.
2. Implement your HMAC validation function
   • Before setting up / turning on new events for webhook requests, you should create a function which validates the authenticity of the HMAC secret key.
   • This function should take the raw request body, secret key and the HMAC signature as inputs. It should use the same algorithm, SHA-256, to produce a computed HMAC and then compare this value with the one sent in the webhook header under the field X-HMAC-Signature.
   • 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.
3. Webhook Endpoint configuration
   • Make sure that your endpoint is set up to receive POST requests and can extract the HMAC signature from the header data.
   • From here, you can move to the Configuration page which involves the setup of your endpoint for receiving requests, selection of events to subscribe to, state configuration, etc.