Webhook Setup
Configure webhooks to receive real-time notifications about document events.
Overview
Webhooks are HTTP callbacks triggered by specific events in Documenso. When an event occurs (such as a document being signed), Documenso sends an HTTP POST request to your configured URL with details about the event.
Common use cases include:
- Syncing document status with your database
- Triggering automated workflows when documents are signed
- Integrating with CRM systems or other third-party services
- Sending custom notifications to stakeholders
Webhooks are available for teams only. Personal accounts cannot configure webhooks.
Creating a Webhook Endpoint
Before configuring a webhook in Documenso, you need an endpoint that can receive HTTP POST requests. Here's a minimal example:
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/documenso', (req, res) => {
const { event, payload, createdAt } = req.body;
console.log(`Received event: ${event}`);
console.log(`Document ID: ${payload.id}`);
console.log(`Document title: ${payload.title}`);
// Process the webhook event
switch (event) {
case 'DOCUMENT_COMPLETED':
// Handle completed document
break;
case 'DOCUMENT_SIGNED':
// Handle signed document
break;
// Handle other events...
}
// Respond with 200 OK to acknowledge receipt
res.status(200).json({ received: true });
});
app.listen(3000, () => {
console.log('Webhook server running on port 3000');
});from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/webhooks/documenso', methods=['POST'])
def handle_webhook():
data = request.get_json()
event = data.get('event')
payload = data.get('payload')
print(f"Received event: {event}")
print(f"Document ID: {payload.get('id')}")
print(f"Document title: {payload.get('title')}")
# Process the webhook event
if event == 'DOCUMENT_COMPLETED':
# Handle completed document
pass
elif event == 'DOCUMENT_SIGNED':
# Handle signed document
pass
# Respond with 200 OK to acknowledge receipt
return jsonify({'received': True}), 200
if __name__ == '__main__':
app.run(port=3000)package main
import (
"encoding/json"
"fmt"
"net/http"
)
type WebhookPayload struct {
Event string `json:"event"`
Payload map[string]interface{} `json:"payload"`
CreatedAt string `json:"createdAt"`
}
func webhookHandler(w http.ResponseWriter, r *http.Request) {
var data WebhookPayload
if err := json.NewDecoder(r.Body).Decode(&data); err != nil {
http.Error(w, "Invalid payload", http.StatusBadRequest)
return
}
fmt.Printf("Received event: %s\n", data.Event)
fmt.Printf("Document ID: %v\n", data.Payload["id"])
fmt.Printf("Document title: %v\n", data.Payload["title"])
// Process the webhook event
switch data.Event {
case "DOCUMENT_COMPLETED":
// Handle completed document
case "DOCUMENT_SIGNED":
// Handle signed document
}
// Respond with 200 OK to acknowledge receipt
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
json.NewEncoder(w).Encode(map[string]bool{"received": true})
}
func main() {
http.HandleFunc("/webhooks/documenso", webhookHandler)
fmt.Println("Webhook server running on port 3000")
http.ListenAndServe(":3000", nil)
}Always respond with a 200 OK status within 30 seconds. Documenso will retry failed deliveries.
Configuring Webhooks in Documenso via the Dashboard
Navigate to team settings
Click your avatar in the top right corner and select Team settings from the dropdown menu.
Configure the webhook
Fill in the following fields:
| Field | Description |
|---|---|
| Webhook URL | The HTTPS endpoint that will receive webhook events |
| Events | Select which events should trigger this webhook |
| Secret (optional) | A secret key used to sign the payload for verification |
Save the webhook
Click Create Webhook to save your configuration. The webhook is now active and will receive events.
Webhook URL Requirements
Your webhook endpoint must meet these requirements:
| Requirement | Details |
|---|---|
| Protocol | HTTPS required (HTTP not allowed in production) |
| Response | Must return 2xx status code within 30 seconds |
| Method | Must accept HTTP POST requests |
| Content-Type | Must accept application/json payloads |
| Availability | Must be publicly accessible from the internet |
For local development, use a tunneling service like ngrok or localtunnel to expose your local server.
Selecting Events
When creating a webhook, you can subscribe to one or more events:
| Event | Trigger |
|---|---|
DOCUMENT_CREATED | A new document is created |
DOCUMENT_SENT | A document is sent to recipients |
DOCUMENT_OPENED | A recipient opens the document |
DOCUMENT_SIGNED | A recipient signs the document |
DOCUMENT_COMPLETED | All recipients have signed the document |
DOCUMENT_REJECTED | A recipient rejects the document |
DOCUMENT_CANCELLED | The document owner cancels the document |
You can subscribe to all events or select specific ones based on your needs. For example, if you only need to know when documents are fully signed, subscribe only to DOCUMENT_COMPLETED.
See Webhook Events for detailed payload information for each event type.
Testing Webhooks
Documenso provides a built-in testing feature to verify your webhook endpoint works correctly.
Navigate to webhook details
Go to Team Settings > Webhooks and click on the webhook you want to test.

Click test
Click the Test button in the webhook details page.
Select an event type
Choose which event type you want to simulate from the dropdown.
The test payload contains realistic sample data so you can verify your endpoint processes events correctly. After sending, you can view the response in the webhook call logs.
Viewing Webhook Logs
Each webhook subscription maintains a log of all delivery attempts. To view logs:
Go to Team Settings > Webhooks
Click on a webhook to view its details
Review the logs
Each webhook call shows the following details:
- Status (success/failure)
- Event type
- Timestamp
- Response code
- Request and response bodies
Click any call to see full details including headers and response data.
Resending Failed Webhooks
If a webhook delivery fails, you can manually resend it:
Navigate to the webhook call details page
Click the Resend button
Documenso will attempt to deliver the same payload again
Retry Policy
When a webhook delivery fails (non-2xx response or timeout), Documenso automatically retries with exponential backoff:
| Attempt | Delay |
|---|---|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
After 5 failed attempts, the webhook is marked as failed and no further automatic retries occur. You can manually resend failed webhooks from the dashboard.
If your endpoint consistently fails, consider reviewing your server logs and ensuring your endpoint meets all URL requirements.
Security Best Practices
Next Steps
- Webhook Events - Detailed payload structure for each event type
- Webhook Verification - Secure your webhooks with signature verification


