Securing Webhooks - Godiligent API Documentation

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

When creating a webhook in our system, specify a unique secret key. This secret should be a strong, randomly generated string.
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:

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

(Python)

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)

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.

​How to Secure Webhook Deliveries

​How It Works

​Step 1: Configuring Your Webhook Secret

​Step 2: Receiving Webhook Payloads

​Step 3: Validating the Webhook Signature

​(Python)

​(JavaScript)

​Security Considerations