> ## Documentation Index
> Fetch the complete documentation index at: https://docs.godiligent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Securing Webhooks

> Guide to securely configure and validate webhook deliveries using a shared secret

## How to Secure Webhook Deliveries

To ensure that webhook payloads are securely transmitted and verified. This guide explains how to configure and validate
webhook deliveries using a shared secret.

### How It Works

When setting up a webhook, a secret is configured on both the sender (our system) and the receiver (your endpoint). Each
webhook payload is signed using this secret, allowing the receiver to verify its authenticity.

#### Step 1: Configuring Your Webhook Secret

1. When creating a webhook in our system, specify a unique secret key. This secret should be a strong, randomly
   generated string.
2. Store this secret securely on your server; it should never be exposed publicly.

#### Step 2: Receiving Webhook Payloads

When your server receives a webhook event, the request will include an `X-Signature` header containing a HMAC signature
of the payload.

Example header:

```
X-Signature: sha256=abcdef1234567890...
```

#### Step 3: Validating the Webhook Signature

To verify the webhook payload:

1. Retrieve the `X-Signature` value from the request headers.
2. Compute the HMAC SHA-256 signature of the request payload using your webhook secret.
3. Compare the computed signature with the one in the `X-Signature` header.
4. If they match, the webhook is valid.

#### (Python)

```python theme={null}
import hashlib
import hmac
import json

def verify_webhook_signature(secret, payload, signature):
  computed_signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
  expected_signature = f"sha256={computed_signature}"
  return hmac.compare_digest(expected_signature, signature)

# Example usage:
secret = "your_webhook_secret"
payload = json.dumps({"event": "example"})
received_signature = "sha256=abcdef1234567890..."

if verify_webhook_signature(secret, payload, received_signature):
  print("Valid webhook received!")
else:
  print("Invalid webhook signature!")
```

#### (JavaScript)

```javascript theme={null}
const crypto = require('crypto');

function verifyWebhookSignature (secret, payload, signature) {
const computedSignature = `sha256=${crypto.createHmac('sha256', secret)
.update(payload)
.digest('hex')}`;
return crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(signature));
}

// Example usage:
const secret = "your_webhook_secret";
const payload = JSON.stringify({ event: "example" });
const receivedSignature = "sha256=abcdef1234567890...";

if (verifyWebhookSignature(secret, payload, receivedSignature)) {
console.log("Valid webhook received!");
} else {
console.log("Invalid webhook signature!");
}
```

#### Security Considerations

* Always use HTTPS to prevent interception of webhook payloads.
* Reject webhook requests that fail signature validation.
* Rotate secrets periodically to enhance security.

By following this guide, you ensure that webhook deliveries are secure and trusted.