Securing your Endpoint

Securing your endpoint is of utmost importance to protect sensitive information and maintain the integrity of your data. Whether it's personally identifiable information (PII), proprietary data, or confidential business data, a compromised endpoint can lead to severe consequences such as data breaches, financial loss, and damage to your organization's reputation.

To ensure the security of your endpoint, utilize an HTTPS endpoint. HTTPS (Hypertext Transfer Protocol Secure) encrypts the data transmitted between the client and the server, preventing unauthorized access and eavesdropping. By encrypting the communication, HTTPS ensures that sensitive information remains confidential and protected from interception. Ensure your HTTPS certificate is issued from a recognized certificate authority. The payloads sent to your endpoint may contain sensitive data, and its crucial this data be encrypted in transit. Cirrus Insight will refused unencrypted endpoints.

Additionally, Cirrus Insight webhooks implement payload signing to add an extra layer of security. By signing the payload, you can verify that it has not been tampered with and that it originated from Cirrus Insight. This is achieved by generating a cryptographic hash of the payload and comparing it with the signature provided in the request. If the signatures match, it indicates that the payload has not been modified during transit and can be trusted.

Keeping Secrets

Keeping the signing key secret is crucial to ensure the security of the webhook system. If the signing key falls into the wrong hands, malicious actors could tamper with the payload or impersonate the sender, compromising the integrity and trustworthiness of the data.

Never expose your signing key in client side code - it should only be used server-side.

By combining these two methods, you can significantly enhance the security of your endpoint and mitigate the risks associated with unauthorized access, data tampering, and impersonation. In the following sections, we will delve into the details of each method and provide guidance on their implementation.

Signing a Payload with the Signing Key

---

1. Extract the CirrusInsight-Signature header from the HTTP request. The header contains two pieces of information to validate the payload, formatted as t=1717686459856,sig=base64encodedsignature=. Split the two parts of the signature header to get a timestamp t and the signature sig.
2. Use the timestamp to reconstruct an unsigned payload. The unsigned payload is made by concatenating the timestamp with the request body, separating the two with a period (.).
3. Generate a SHA256 HMAC (Hash-based Message Authentication Code) of the unsigned payload using the secret signing key that was issued when you set up your webhook endpoint.
4. Compare the generated HMAC with the sig property from the CirrusInsight-Signature header. If the two match, you have validated that the request is legitimate and originates from Cirrus Insight.

Examples

We have provided some example endpoints that include validating the signature. Refer to the Endpoint Examples for more information.