diff --git a/docs/docs/help/Settings/Webhook.md b/docs/docs/help/Settings/Webhook.md index 219cbffc6..f34d1f2f1 100644 --- a/docs/docs/help/Settings/Webhook.md +++ b/docs/docs/help/Settings/Webhook.md @@ -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) +Navigate to Add Webhook **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. + +webhook security key + +โš ๏ธ **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.