diff --git a/docs/docs/help/Settings/Webhook.md b/docs/docs/help/Settings/Webhook.md index 62d9064a2..219cbffc6 100644 --- a/docs/docs/help/Settings/Webhook.md +++ b/docs/docs/help/Settings/Webhook.md @@ -9,7 +9,9 @@ title: Webhook A **webhook** allows one system (like OpenSign) to automatically send real-time data or notifications to another system (like your server) when a specific event occurs. -Think of it like a **push notification for your backend** β€” instead of constantly checking for updates (polling), a webhook sends data to your endpoint **as soon as an event happens**. +Think of it as a **push notification for your backend** β€” instead of continuously checking for updates (polling), a webhook pushes data to your endpoint **as soon as an event happens**. + +--- ## 🧠 Simple Example @@ -24,15 +26,15 @@ Suppose you're using OpenSign to collect eSignatures: ## 🧭 How to Add a Webhook in OpenSign **Step 1:** Log in to your OpenSign account using your credentials. -**Step 2:** Navigate to **Settings β†’ Webhook**. +**Step 2:** Navigate to **Settings β†’ Webhook**. ![Navigate to Add Webhook](https://github.com/user-attachments/assets/6b069b6c-d2b7-408b-b7c9-7fbeb55d6c98) -**Step 3:** Click on **Add Webhook**. +**Step 3:** Click **Add Webhook**. - A popup will appear. Enter your **Webhook URL** and click **Yes** to save it. -**Note:** To enable **Live Webhook** support, you must upgrade to a **paid plan** β€” either the **Professional** or **Teams** plan. +> **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) @@ -40,8 +42,14 @@ Suppose you're using OpenSign to collect eSignatures: ## πŸ§ͺ Sandbox Webhook -- You can also add webhooks for the **Sandbox** environment on the same page. -- **Sandbox Webhooks are available in all plans**, including the **free plan**, and are ideal for development and testing purposes. +- You can also add webhook for the **Sandbox** environment on the same page. +- **Sandbox webhook** are available on all plans, including the **Free** plan, and are ideal for development and testing. + +> **Caution:** Avoid sending sensitive or confidential data to the Sandbox environment. + +πŸ“˜ **API Reference:** +You can also manage your webhooks via our API. +See the API documentation here: [Save/Update Webhook API](https://docs.opensignlabs.com/docs/API-docs/save-update-webhook) --- @@ -53,11 +61,13 @@ OpenSign sends event notifications to your configured webhook URL when any of th - **Document Viewed** – A signer viewed the document. - **Document Signed** – A signer signed the document. - **Document Completed** – All required signatures are completed. -- **Document Revoked or Declined** – Document signing was revoked or declined. +- **Document Revoked or Declined** – The document was revoked or declined. Each notification is sent as a **POST request** with a **JSON payload** containing relevant event data. -### Example Payload: Document Created +--- + +### πŸ” Example Payload: `Document Created` ```json { @@ -72,35 +82,135 @@ Each notification is sent as a **POST request** with a **JSON payload** containi { "name": "Peter Mark", "email": "peter.mark1093@gmail.com", - "phone": "9283784545554" + "phone": "3556567789" } ], "createdAt": "Fri, 16 May 2025 15:02:42 IST" } +``` +### πŸ” Example Payload: `Document Viewed` +```json +{ + "event": "viewed", + "type": "request-sign", + "objectId": "kpeg6Q2rO7", + "file": "https://legadratw3d.ams3.digitaloceanspaces.com/851de61f62b60a1f62e03232464fa4bf_81wV17MTebsrRoov.pdf?...", + "name": "Sample Test Doc", + "note": "Please review and sign this document", + "description": "", + "signers": [ + { + "name": "Peter Mark", + "email": "peter.mark1093@gmail.com", + "phone": "3556567789" + } + ], + "viewedBy": "peter.mark1093@gmail.com", + "viewedAt": "Fri, 16 May 2025 16:18:16 IST", + "createdAt": "Fri, 16 May 2025 15:02:28 IST" +} ``` --- +### πŸ” Example Payload: `Document Signed` + +```json +{ + "event": "signed", + "type": "request-sign", + "objectId": "kpeg6Q2rO7", + "file": "https://legadratw3d.ams3.digitaloceanspaces.com/bc2eb56cc9d29a5f222e4a4b5dbbcfbf_signed_sample_test_doc_4858.pdf?...", + "name": "Sample Test Doc", + "note": "Please review and sign this document", + "description": "", + "signer": { + "name": "Peter Mark", + "email": "peter.mark1093@gmail.com", + "phone": "3556567789" + }, + "signedAt": "Fri, 16 May 2025 16:18:34 GMT+5:30", + "createdAt": "Fri, 16 May 2025 15:02:28 GMT+5:30" +} +``` + +--- + +### πŸ” Example Payload: `Document Completed` + +```json +{ + "event": "completed", + "type": "request-sign", + "objectId": "kpeg6Q2rO7", + "file": "https://legadratw3d.ams3.digitaloceanspaces.com/bc2eb56cc9d29a5f222e4a4b5dbbcfbf_signed_sample_test_doc_4858.pdf?...", + "certificate": "https://legadratw3d.ams3.digitaloceanspaces.com/9c954912f529acb7e4d065ec0521a63b_certificate.pdf?...", + "name": "Sample Test Doc", + "note": "Please review and sign this document", + "description": "", + "signers": [ + { + "name": "Peter Mark", + "email": "peter.mark1093@gmail.com", + "phone": "3556567789" + } + ], + "completedAt": "Fri, 16 May 2025 16:18:35 GMT+5:30", + "createdAt": "Fri, 16 May 2025 15:02:28 GMT+5:30" +} +``` +--- + +### πŸ” Example Payload: `Document Declined` + +```json +{ + "event": "declined", + "type": "request-sign", + "objectId": "1gtDMBHpEY", + "file": "https://legadratw3d.ams3.digitaloceanspaces.com/e90c32a45351eb52eb00e0054ae50566_581ZmOn4CwAqnxSF.pdf?...", + "name": "Sample Test Doc ", + "note": "Please review and sign this document", + "description": "", + "signers": [ + { + "name": "Peter Mark", + "email": "peter.mark1093@gmail.com", + "phone": "9283784545554" + } + ], + "declinedBy": "peter.mark1093@gmail.com", + "declinedReason": "Invalid date format used.", + "declinedAt": "Fri, 16 May 2025 16:25:38 IST", + "createdAt": "Fri, 16 May 2025 16:24:28 IST" +} +``` +--- + ## ❓ Frequently Asked Questions ### 1. What is the OpenSign Sandbox environment? -The Sandbox is a testing environment designed for developers to safely experiment with OpenSign APIs and workflows. It mirrors the live environment but has testing limitations. + +The Sandbox is a testing environment designed for developers to safely experiment with OpenSign APIs and workflows. It mirrors the live environment but with testing limitations. --- ### 2. Can I use my Live Webhook in the Sandbox? -No. Live Webhooks do not work in the Sandbox environment. You must configure a separate webhook specifically for Sandbox testing. +No. **Live Webhooks do not work** in the Sandbox environment. You must configure a separate webhook specifically for Sandbox testing. --- ### 3. Can I test all webhook events in the Sandbox? -Yes, the Sandbox environment supports all event types, including `created`, `viewed`, `signed`, `completed`, and `revoked/declined`. However, behavior may be simulated for testing purposes. +Yes. The Sandbox environment supports all event types, including `created`, `viewed`, `signed`, `completed`, and `revoked/declined`. +However, some behaviors may be simulated for testing purposes. --- -If you need help testing your webhook or integrating it into your application, feel free to contact our support team at [support@opensignlabs.com](mailto:support@opensignlabs.com). +## πŸ’¬ Need Help? + +If you need help testing your webhook or integrating it into your application, feel free to reach out to our support team at [support@opensignlabs.com](mailto:support@opensignlabs.com). **Happy signing with OpenSignβ„’!**