How to Secure and Validate Webhooks

In this guide, we’ll show you how to add a security layer to the webhooks you receive from Common Ninja by using HMAC signature verification. This ensures the webhook's authenticity and protects against tampered or fraudulent data.

Overview

HMAC (Hash-based Message Authentication Code) uses a secret key to generate a unique signature for each webhook payload. You’ll verify this signature on your end to ensure that the webhook truly comes from Common Ninja.

Step 1: Set Up Your Encryption Key

To validate the webhooks, you need to configure an encryption key that will be used to generate the HMAC signature.

1. Go to the Notifications Settings section in your widget editor.
2. Under the Webhooks settings, find the option to set up your encryption key.
3. Enter a secure key and save it. This key will be used by Common Ninja to sign the webhook payloads.
   

Make sure you store this key securely on your server, as it will be required to verify the webhooks.

Step 2: Receiving Webhooks

When Common Ninja sends a webhook to your endpoint, the request will contain:

• Payload: The actual data in JSON format.
• CN-Webhook-Signature: A custom HTTP header that includes the HMAC signature.

Example headers:

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
CN-Webhook-Signature: d4c2b8f9a0a5c6e13bfa2f3b...

Step 3: Verifying the Webhook Signature

To confirm that the webhook is legitimate, follow these steps:

1. Extract the Payload: Grab the JSON payload from the webhook.

2. Extract the CN-Webhook-Signature Header: Capture the value of the CN-Webhook-Signature header.

3. Generate the HMAC Signature: Using the same encryption key you provided in Step 1, compute the HMAC of the payload.

4. Compare Signatures: Check that the computed HMAC matches the CN-Webhook-Signature header. If they match, the webhook is valid.

Here’s an example of verifying the webhook signature using Node.js:

const crypto = require('crypto'); 

// Your encryption key 
const secretKey = 'your_secret_key';

// The received webhook payload (as a string)
const receivedPayload = JSON.stringify(req.body);

// Signature from the CN-Signature header
const receivedSignature = headers['CN-Webhook-Signature'];

// Generate the HMAC signature
const computedHmac = crypto.createHmac('sha256', secretKey).update(receivedPayload).digest('hex');

// Compare the signatures
if (computedHmac === receivedSignature) {
   console.log('Webhook is valid');
} else {
   console.log('Invalid webhook');
}

Step 4: Handling Invalid Webhooks

If the computed HMAC does not match the CN-Webhook-Signature header, the webhook may have been tampered with or it didn’t originate from Common Ninja. Reject the webhook and log the event for further analysis.

Common Issues

• Signature Mismatch: This could happen if the payload was altered or an incorrect encryption key is being used.
• Missing CN-Webhook-Signature Header: If the header is absent, the request did not come from Common Ninja, so it should be rejected.

Best Practices

• Keep your encryption key secure: Ensure that only trusted systems have access to your key.
• Rotate keys periodically: For enhanced security, regularly rotate your encryption key and update it in both Common Ninja and your verification system.
• Log webhook requests: Maintain logs of all webhook requests to help trace issues or security breaches.

By following these steps, you can securely validate webhooks from Common Ninja and ensure that your application processes only legitimate requests.

If you encounter any problems, feel free to reach out to our support team!