Diligent Webhooks API

## How to Secure Webhook DeliveriesTo ensure that webhook payloads are securely transmitted and verified. This guide explains how to configure and validatewebhook deliveries using a shared secret.### How It WorksWhen setting up a webhook, a secret is configured on both the sender (our system) and the receiver (your endpoint). Eachwebhook payload is signed using this secret, allowing the receiver to verify its authenticity.#### Step 1: Configuring Your Webhook Secret1. When creating a webhook in our system, specify a unique secret key. This secret should be a strong, randomlygenerated string.2. Store this secret securely on your server; it should never be exposed publicly.#### Step 2: Receiving Webhook PayloadsWhen your server receives a webhook event, the request will include an `X-Signature` header containing a HMAC signatureof the payload.Example header:```X-Signature: sha256=abcdef1234567890...```#### Step 3: Validating the Webhook SignatureTo 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)```pythonimport hashlibimport hmacimport jsondef 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)```javascriptconst 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.