Merge pull request #2057 from pravinOpenSign/patch-51

2026-08-25 00:52:34 +02:00 · 2025-12-19 21:46:03 +05:30
parent efa5e2e491 cb9f75bf2f
commit 0994f80891
1 changed files with 113 additions and 2 deletions
@@ -28,7 +28,7 @@ Suppose you're using OpenSign to collect eSignatures:
 **Step 1:** Log in to your OpenSign account using your credentials.  
 **Step 2:** Navigate to **Settings → Webhook**.

-![Navigate to Add Webhook](https://github.com/user-attachments/assets/6b069b6c-d2b7-408b-b7c9-7fbeb55d6c98)
+<img width="861" height="407" alt="Navigate to Add Webhook" src="https://github.com/user-attachments/assets/883dc914-9316-42b0-b59c-10b168265b38" />

 **Step 3:** Click **Add Webhook**.

@@ -36,10 +36,121 @@ Suppose you're using OpenSign to collect eSignatures:

 > **Note:** To enable **Live Webhook** support, you must upgrade to a **paid plan** — either the **Professional** or **Teams** plan.

-![Add Webhook](https://github.com/user-attachments/assets/ff68b255-a6e6-4a7d-9cef-6dd9e3b6d4e4)
+---
+
+## 🧭 How to Create a Webhook Security Key
+
+A **Webhook Security Key** (also called a webhook secret) is a shared secret used to verify that webhook requests are genuinely sent by OpenSign and have not been tampered with.
+
+### Steps to Create a Webhook Security Key
+
+1. Log in to your **OpenSign** account.
+2. Navigate to **Settings → Webhooks**.
+3. Add or edit a webhook endpoint.
+4. Generate a Security Key by clicking Enable Authentication, then click the Generate button.
+The webhook security key has been generated.
+   - Example: `a50a904a2a329d761781dac27c984416a07396736ac5588b62c6fe226538fbca`
+6. Save the webhook configuration.
+   
+<img width="861" height="600" alt="webhook security key" src="https://github.com/user-attachments/assets/6f61a23e-25a1-4785-b241-657af0c1eeb1" />
+
+⚠️ **Important:** Store this key securely. Do not expose it in client-side code or public repositories.

 ---

+## 🔐 How the Webhook Security Key Works
+
+OpenSign signs every webhook request using your security key.
+
+### High-level Flow
+
+1. An event occurs (e.g. create document, document viewed, signed, completed, and declined).
+2. OpenSign sends a webhook request to your configured endpoint.
+3. OpenSign generates a signature using:
+   - The **raw request payload**
+   - Your **webhook security key**
+   - The **HMAC-SHA256** algorithm
+4. The generated signature is sent in the request header:
+
+```
+x-webhook-signature
+```
+
+5. Your server recomputes the signature using the same payload and secret.
+6. If both signatures match, the request is verified as authentic.
+
+---
+
+// Process webhook event
+```
+
+---
+
+## 📦 Sample Webhook Payload
+
+```json
+const crypto = require("crypto");
+
+function verifySignature(req, secret) {
+  const receivedSignature = req.headers["x-webhook-signature"];
+  const payload = req.body;
+
+  const expectedSignature = crypto
+    .createHmac("sha256", secret)
+    .update(JSON.stringify(payload))
+    .digest("hex");
+
+  return receivedSignature === expectedSignature;
+}
+
+console.log("Try programiz.pro", verifySignature({body: {
+  "event": "created",
+  "type": "request-sign",
+  "objectId": "SBEbnHwfrN",
+  "file": "https://legadratw3d.ams3.digitaloceanspaces.com/c3f0bc11b84a87e6265de6bf28e5015e_uoeksXXU6FI5Op2B.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=DO00QAPRB3CQRWHWQ8ZB%2F20251219%2Fus-west%2Fs3%2Faws4_request&X-Amz-Date=20251219T152806Z&X-Amz-Expires=900&X-Amz-Signature=9635dfb8ee8fde933f881905a97f869578ef7e99b337d4b21a0805b8317fd70d&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject",
+  "name": "Sample Test Doc Line Compressed",
+  "note": "Please review and sign this document",
+  "description": "",
+  "signers": [
+    {
+      "name": "Peter Mark",
+      "email": "peter.mark@opensignlabs.com"
+    },
+    {
+      "name": "kelvin bosch",
+      "email": "kelvin.bosch@opensignlabs.com"
+    }
+  ],
+  "createdAt": "Sat, 20 Dec 2025 00:58:20 GMT+9:30"
+}, headers:{"x-webhook-signature":"52958fd3900f19ba6485319eb2622ef0ec4cf5ddfe36509cbe95eb706ed6b8c2" }}, "0906e8cbc88da0d5a6fd78162eb8e5e57ba7bd99bdc472145dc089d7f82b0a4a"));
+```
+
+The corresponding signature is sent in the request header:
+
+```
+x-webhook-signature: bcf57b06dde0c030d9423639824bad17ab7dd09ea3bf0a743773b95254ecf78e
+```
+If the script returns true, it means the webhook is valid and has not been tampered with.
+
+## ✅ Best Practices
+
+- Always verify the webhook signature before processing the payload.
+- Use the **raw request body** for signature calculation (avoid modifying it).
+- Rotate your webhook security key periodically.
+- Return a **2xx** HTTP status only after successful verification.
+
+---
+
+## 🧩 Common Issues
+
+- **Signature mismatch**: Ensure the payload is stringified exactly as received.
+- **Missing header**: Confirm `x-webhook-signature` is present in the request.
+- **Wrong secret**: Verify the same security key is used on both sides.
+
+---
+
+This mechanism ensures webhook requests are secure, tamper-proof, and trustworthy.
+
 ## 🧪 Sandbox Webhook

 - You can also add webhook for the **Sandbox** environment on the same page.