mirror of
https://github.com/documenso/documenso.git
synced 2025-11-11 04:52:41 +10:00
8367878395
## Description <!--- Describe the changes introduced by this pull request. --> <!--- Explain what problem it solves or what feature/fix it adds. --> ## Related Issue <!--- If this pull request is related to a specific issue, reference it here using #issue_number. --> <!--- For example, "Fixes #123" or "Addresses #456". --> ## Changes Made <!--- Provide a summary of the changes made in this pull request. --> <!--- Include any relevant technical details or architecture changes. --> - Change 1 - Change 2 - ... ## Testing Performed <!--- Describe the testing that you have performed to validate these changes. --> <!--- Include information about test cases, testing environments, and results. --> - Tested feature X in scenario Y. - Ran unit tests for component Z. - Tested on browsers A, B, and C. - ... ## Checklist <!--- Please check the boxes that apply to this pull request. --> <!--- You can add or remove items as needed. --> - [ ] I have tested these changes locally and they work as expected. - [ ] I have added/updated tests that prove the effectiveness of these changes. - [ ] I have updated the documentation to reflect these changes, if applicable. - [ ] I have followed the project's coding style guidelines. - [ ] I have addressed the code review feedback from the previous submission, if applicable. ## Additional Notes <!--- Provide any additional context or notes for the reviewers. --> <!--- This might include details about design decisions, potential concerns, or anything else relevant. --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Enhanced project README for clarity and improved environment variables section. - Added comprehensive developer and user documentation, including guides on local development, public API, self-hosting, and compliance standards. - Introduced specific guides for contributing, creating API keys, using webhooks, and setting up security measures. - Detailed documentation on various fields available for document signing to improve user understanding. - Added metadata structuring to improve navigation within the documentation site. - **Chores** - Updated `.gitignore` to better handle project files. - **New Features** - Introduced detailed metadata and documentation for various Documenso functionalities, including signing documents, user profiles, and compliance levels. - Added functionality for Direct Link Signing, enabling easy sharing for document signing. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Timur Ercan <timur.ercan31@gmail.com> Co-authored-by: Lucas Smith <me@lucasjamessmith.me> Co-authored-by: David Nguyen <davidngu28@gmail.com>
351 lines
14 KiB
Plaintext
351 lines
14 KiB
Plaintext
---
|
|
title: Webhooks
|
|
description: Learn how to use webhooks to receive real-time notifications about your documents.
|
|
---
|
|
|
|
# Webhooks
|
|
|
|
Webhooks are HTTP callbacks triggered by specific events. When the user subscribes to a specific event, and that event occurs, the webhook makes an HTTP request to the URL provided by the user. The request can be a simple notification or carry a payload with more information about the event.
|
|
|
|
Some of the common use cases for webhooks include:
|
|
|
|
1. **Real-time Data Syncing**: Webhooks provide a way to keep data in sync across different platforms. For example, you can keep your system up-to-date with your Documenso documents by subscribing to events like document creation or signing.
|
|
2. **Automating Workflows**: They can trigger automated workflows that start when an event occurs. For example, the webhook could trigger an email when a document is signed.
|
|
3. **Integrating Third-Party Services**: Webhooks can be used to integrate Documenso with third-party services. For example, you could use a webhook to send data to a CRM system when a document is signed.
|
|
|
|
Documenso supports Webhooks and allows you to subscribe to the following events:
|
|
|
|
- `document.created`
|
|
- `document.sent`
|
|
- `document.opened`
|
|
- `document.signed`
|
|
- `document.completed`
|
|
|
|
## Create a webhook subscription
|
|
|
|
You can create a webhook subscription from the user settings page. Click on your avatar in the top right corner of the dashboard and select "**[User settings](https://app.documenso.com/settings)**" from the dropdown menu.
|
|
|
|
|
|
|
|
Then, navigate to the "**[Webhooks](https://app.documenso.com/settings/webhooks)**" tab, where you can see a list of your existing webhooks and create new ones.
|
|
|
|
|
|
|
|
Clicking on the "**Create Webhook**" button opens a modal to create a new webhook subscription.
|
|
|
|
To create a new webhook subscription, you need to provide the following information:
|
|
|
|
- Enter the webhook URL that will receive the event payload.
|
|
- Select the event(s) you want to subscribe to: `document.created`, `document.sent`, `document.opened`, `document.signed`, `document.completed`.
|
|
- Optionally, you can provide a secret key that will be used to sign the payload. This key will be included in the `X-Documenso-Signature` header of the request.
|
|
|
|
|
|
|
|
After you have filled in the required information, click on the "**Create Webhook**" button to save your subscription.
|
|
|
|
The screenshot below illustrates a newly created webhook subscription.
|
|
|
|
|
|
|
|
You can edit or delete your webhook subscriptions by clicking the "**Edit**" or "**Delete**" buttons next to the webhook.
|
|
|
|
## Webhook fields
|
|
|
|
The payload sent to the webhook URL contains the following fields:
|
|
|
|
| Field | Type | Description |
|
|
| -------------------------------------------- | --------- | ---------------------------------------------------- |
|
|
| `event` | string | The type of event that triggered the webhook. |
|
|
| `payload.id` | number | The id of the document. |
|
|
| `payload.userId` | number | The id of the user who owns the document. |
|
|
| `payload.authOptions` | json? | Authentication options for the document. |
|
|
| `payload.formValues` | json? | Form values for the document. |
|
|
| `payload.title` | string | The name of the document. |
|
|
| `payload.status` | string | The current status of the document. |
|
|
| `payload.documentDataId` | string | The identifier for the document data. |
|
|
| `payload.createdAt` | datetime | The creation date and time of the document. |
|
|
| `payload.updatedAt` | datetime | The last update date and time of the document. |
|
|
| `payload.completedAt` | datetime? | The completion date and time of the document. |
|
|
| `payload.deletedAt` | datetime? | The deletion date and time of the document. |
|
|
| `payload.teamId` | number? | The id of the team. |
|
|
| `payload.documentData.id` | string | The id of the document data. |
|
|
| `payload.documentData.type` | string | The type of the document data. |
|
|
| `payload.documentData.data` | string | The data of the document. |
|
|
| `payload.documentData.initialData` | string | The initial data of the document. |
|
|
| `payload.Recipient[].id` | number | The id of the recipient. |
|
|
| `payload.Recipient[].documentId` | number? | The id the document associated with the recipient. |
|
|
| `payload.Recipient[].templateId` | number? | The template identifier for the recipient. |
|
|
| `payload.Recipient[].email` | string | The email address of the recipient. |
|
|
| `payload.Recipient[].name` | string | The name of the recipient. |
|
|
| `payload.Recipient[].token` | string | The token associated with the recipient. |
|
|
| `payload.Recipient[].expired` | datetime? | The expiration status of the recipient. |
|
|
| `payload.Recipient[].signedAt` | datetime? | The date and time the recipient signed the document. |
|
|
| `payload.Recipient[].authOptions.accessAuth` | json? | Access authentication options. |
|
|
| `payload.Recipient[].authOptions.actionAuth` | json? | Action authentication options. |
|
|
| `payload.Recipient[].role` | string | The role of the recipient. |
|
|
| `payload.Recipient[].readStatus` | string | The read status of the document by the recipient. |
|
|
| `payload.Recipient[].signingStatus` | string | The signing status of the recipient. |
|
|
| `payload.Recipient[].sendStatus` | string | The send status of the document to the recipient. |
|
|
| `createdAt` | datetime | The creation date and time of the webhook event. |
|
|
| `webhookEndpoint` | string | The endpoint URL where the webhook is sent. |
|
|
|
|
## Webhook event payload example
|
|
|
|
When an event that you have subscribed to occurs, Documenso will send a POST request to the specified webhook URL with a payload containing information about the event.
|
|
|
|
## Example payloads
|
|
|
|
Below are examples of the payloads that are sent for each of the supported events. The payloads are sent as JSON data in the body of the POST request.
|
|
|
|
Example payload for the `document.created` event:
|
|
|
|
```json
|
|
{
|
|
"event": "DOCUMENT_CREATED",
|
|
"payload": {
|
|
"id": 10,
|
|
"userId": 1,
|
|
"authOptions": null,
|
|
"formValues": null,
|
|
"title": "documenso.pdf",
|
|
"status": "DRAFT",
|
|
"documentDataId": "hs8qz1ktr9204jn7mg6c5dxy0",
|
|
"createdAt": "2024-04-22T11:44:43.341Z",
|
|
"updatedAt": "2024-04-22T11:44:43.341Z",
|
|
"completedAt": null,
|
|
"deletedAt": null,
|
|
"teamId": null
|
|
},
|
|
"createdAt": "2024-04-22T11:44:44.779Z",
|
|
"webhookEndpoint": "https://mywebhooksite.com/mywebhook"
|
|
}
|
|
```
|
|
|
|
Example payload for the `document.sent` event:
|
|
|
|
```json
|
|
{
|
|
"event": "DOCUMENT_SENT",
|
|
"payload": {
|
|
"id": 10,
|
|
"userId": 1,
|
|
"authOptions": null,
|
|
"formValues": null,
|
|
"title": "documenso.pdf",
|
|
"status": "PENDING",
|
|
"documentDataId": "hs8qz1ktr9204jn7mg6c5dxy0",
|
|
"createdAt": "2024-04-22T11:44:43.341Z",
|
|
"updatedAt": "2024-04-22T11:48:07.569Z",
|
|
"completedAt": null,
|
|
"deletedAt": null,
|
|
"teamId": null,
|
|
"Recipient": [
|
|
{
|
|
"id": 52,
|
|
"documentId": 10,
|
|
"templateId": null,
|
|
"email": "signer2@documenso.com",
|
|
"name": "Signer 2",
|
|
"token": "vbT8hi3jKQmrFP_LN1WcS",
|
|
"expired": null,
|
|
"signedAt": null,
|
|
"authOptions": {
|
|
"accessAuth": null,
|
|
"actionAuth": null
|
|
},
|
|
"role": "VIEWER",
|
|
"readStatus": "NOT_OPENED",
|
|
"signingStatus": "NOT_SIGNED",
|
|
"sendStatus": "SENT"
|
|
},
|
|
{
|
|
"id": 53,
|
|
"documentId": 10,
|
|
"templateId": null,
|
|
"email": "signer1@documenso.com",
|
|
"name": "Signer 1",
|
|
"token": "HkrptwS42ZBXdRKj1TyUo",
|
|
"expired": null,
|
|
"signedAt": null,
|
|
"authOptions": {
|
|
"accessAuth": null,
|
|
"actionAuth": null
|
|
},
|
|
"role": "SIGNER",
|
|
"readStatus": "NOT_OPENED",
|
|
"signingStatus": "NOT_SIGNED",
|
|
"sendStatus": "SENT"
|
|
}
|
|
]
|
|
},
|
|
"createdAt": "2024-04-22T11:48:07.945Z",
|
|
"webhookEndpoint": "https://mywebhooksite.com/mywebhook"
|
|
}
|
|
```
|
|
|
|
Example payload for the `document.opened` event:
|
|
|
|
```json
|
|
{
|
|
"event": "DOCUMENT_OPENED",
|
|
"payload": {
|
|
"id": 10,
|
|
"userId": 1,
|
|
"authOptions": null,
|
|
"formValues": null,
|
|
"title": "documenso.pdf",
|
|
"status": "PENDING",
|
|
"documentDataId": "hs8qz1ktr9204jn7mg6c5dxy0",
|
|
"createdAt": "2024-04-22T11:44:43.341Z",
|
|
"updatedAt": "2024-04-22T11:48:07.569Z",
|
|
"completedAt": null,
|
|
"deletedAt": null,
|
|
"teamId": null,
|
|
"Recipient": [
|
|
{
|
|
"id": 52,
|
|
"documentId": 10,
|
|
"templateId": null,
|
|
"email": "signer2@documenso.com",
|
|
"name": "Signer 2",
|
|
"token": "vbT8hi3jKQmrFP_LN1WcS",
|
|
"expired": null,
|
|
"signedAt": null,
|
|
"authOptions": {
|
|
"accessAuth": null,
|
|
"actionAuth": null
|
|
},
|
|
"role": "VIEWER",
|
|
"readStatus": "OPENED",
|
|
"signingStatus": "NOT_SIGNED",
|
|
"sendStatus": "SENT"
|
|
}
|
|
],
|
|
"documentData": {
|
|
"id": "hs8qz1ktr9204jn7mg6c5dxy0",
|
|
"type": "S3_PATH",
|
|
"data": "9753/xzqrshtlpokm/documenso.pdf",
|
|
"initialData": "9753/xzqrshtlpokm/documenso.pdf"
|
|
}
|
|
},
|
|
"createdAt": "2024-04-22T11:50:26.174Z",
|
|
"webhookEndpoint": "https://mywebhooksite.com/mywebhook"
|
|
}
|
|
```
|
|
|
|
Example payload for the `document.signed` event:
|
|
|
|
```json
|
|
{
|
|
"event": "DOCUMENT_SIGNED",
|
|
"payload": {
|
|
"id": 10,
|
|
"userId": 1,
|
|
"authOptions": null,
|
|
"formValues": null,
|
|
"title": "documenso.pdf",
|
|
"status": "COMPLETED",
|
|
"documentDataId": "hs8qz1ktr9204jn7mg6c5dxy0",
|
|
"createdAt": "2024-04-22T11:44:43.341Z",
|
|
"updatedAt": "2024-04-22T11:52:05.708Z",
|
|
"completedAt": "2024-04-22T11:52:05.707Z",
|
|
"deletedAt": null,
|
|
"teamId": null,
|
|
"Recipient": [
|
|
{
|
|
"id": 51,
|
|
"documentId": 10,
|
|
"templateId": null,
|
|
"email": "signer1@documenso.com",
|
|
"name": "Signer 1",
|
|
"token": "HkrptwS42ZBXdRKj1TyUo",
|
|
"expired": null,
|
|
"signedAt": "2024-04-22T11:52:05.688Z",
|
|
"authOptions": {
|
|
"accessAuth": null,
|
|
"actionAuth": null
|
|
},
|
|
"role": "SIGNER",
|
|
"readStatus": "OPENED",
|
|
"signingStatus": "SIGNED",
|
|
"sendStatus": "SENT"
|
|
}
|
|
]
|
|
},
|
|
"createdAt": "2024-04-22T11:52:18.577Z",
|
|
"webhookEndpoint": "https://mywebhooksite.com/mywebhook"
|
|
}
|
|
```
|
|
|
|
Example payload for the `document.completed` event:
|
|
|
|
```json
|
|
{
|
|
"event": "DOCUMENT_COMPLETED",
|
|
"payload": {
|
|
"id": 10,
|
|
"userId": 1,
|
|
"authOptions": null,
|
|
"formValues": null,
|
|
"title": "documenso.pdf",
|
|
"status": "COMPLETED",
|
|
"documentDataId": "hs8qz1ktr9204jn7mg6c5dxy0",
|
|
"createdAt": "2024-04-22T11:44:43.341Z",
|
|
"updatedAt": "2024-04-22T11:52:05.708Z",
|
|
"completedAt": "2024-04-22T11:52:05.707Z",
|
|
"deletedAt": null,
|
|
"teamId": null,
|
|
"documentData": {
|
|
"id": "hs8qz1ktr9204jn7mg6c5dxy0",
|
|
"type": "S3_PATH",
|
|
"data": "bk9p1h7x0s3m/documenso-signed.pdf",
|
|
"initialData": "9753/xzqrshtlpokm/documenso.pdf"
|
|
},
|
|
"Recipient": [
|
|
{
|
|
"id": 50,
|
|
"documentId": 10,
|
|
"templateId": null,
|
|
"email": "signer2@documenso.com",
|
|
"name": "Signer 2",
|
|
"token": "vbT8hi3jKQmrFP_LN1WcS",
|
|
"expired": null,
|
|
"signedAt": "2024-04-22T11:51:10.055Z",
|
|
"authOptions": {
|
|
"accessAuth": null,
|
|
"actionAuth": null
|
|
},
|
|
"role": "VIEWER",
|
|
"readStatus": "OPENED",
|
|
"signingStatus": "SIGNED",
|
|
"sendStatus": "SENT"
|
|
},
|
|
{
|
|
"id": 51,
|
|
"documentId": 10,
|
|
"templateId": null,
|
|
"email": "signer1@documenso.com",
|
|
"name": "Signer 1",
|
|
"token": "HkrptwS42ZBXdRKj1TyUo",
|
|
"expired": null,
|
|
"signedAt": "2024-04-22T11:52:05.688Z",
|
|
"authOptions": {
|
|
"accessAuth": null,
|
|
"actionAuth": null
|
|
},
|
|
"role": "SIGNER",
|
|
"readStatus": "OPENED",
|
|
"signingStatus": "SIGNED",
|
|
"sendStatus": "SENT"
|
|
}
|
|
]
|
|
},
|
|
"createdAt": "2024-04-22T11:52:18.277Z",
|
|
"webhookEndpoint": "https://mywebhooksite.com/mywebhook"
|
|
}
|
|
```
|
|
|
|
## Availability
|
|
|
|
Webhooks are available to individual users and teams.
|