Webhooks
Webhooks allow you to receive real-time notifications when documents are completed. Instead of polling the API for document status, QuickSign will send HTTP POST requests to your configured webhook URL.
Setup Webhook URL
To start receiving webhook notifications, you need to configure a webhook URL in your account:
Prepare Your Endpoint
Create an HTTP endpoint in your application that can receive POST requests. This endpoint should:
- Accept POST requests with JSON payload
- Respond with HTTP 200-299 status code
- Process the webhook asynchronously if possible
- Be publicly accessible (not behind a firewall)
Configure Webhook URL
Log in to your QuickSign account and navigate to Settings → API Settings. Enter your webhook URL in the Webhook URL field and save.
Test Your Endpoint
Complete a test document to verify your webhook endpoint receives the notification correctly.
Webhook Payload
When a document status changes to COMPLETED, QuickSign will send a POST request to your webhook URL with the following payload:
Request Headers
Request Body
Payload Fields
Webhook Fields
| Name | Type | Required | Description |
|---|---|---|---|
| documentId | string | Required | UUID of the completed document |
| status | string | Required | Document status (always "COMPLETED" for webhook notifications) |
| downloadUrl | string | Required | Pre-signed S3 URL to download the signed PDF document |
Example Webhook Handler
Node.js (Express)
Python (Flask)
Security Considerations
Verify Request Origin
To ensure webhook requests are genuinely from QuickSign, check the User-Agent header:
HTTPS Required
Your webhook URL must use HTTPS (not HTTP) for security. Self-signed certificates are not supported.
Error Handling
Always respond with an appropriate HTTP status code:
- 200-299: Success - webhook processed successfully
- 400-499: Client error - invalid payload or unauthorized
- 500-599: Server error - temporary failure on your end
Testing Webhooks
Local Development
For local testing, use a tool like ngrok to expose your local server to the internet:
Install ngrok
Start Your Local Server
Create Tunnel
Configure Webhook URL
Use the ngrok URL as your webhook URL in QuickSign API Settings:
Online Testing Tools
Use these services to test webhook delivery without writing code:
- webhook.site: webhook.site - Instantly view webhook payloads
- RequestBin: requestbin.com - Inspect HTTP requests
- Pipedream: pipedream.com - Build workflow automations
Troubleshooting
Not Receiving Webhooks?
If you're not receiving webhook notifications, check:
- ✅ Webhook URL is correctly configured in API Settings
- ✅ Your endpoint is publicly accessible (not localhost)
- ✅ Your endpoint responds with HTTP 200-299
- ✅ You're using HTTPS (not HTTP)
- ✅ No firewall is blocking incoming requests
- ✅ Document status actually changed to COMPLETED
- ✅ Your user account has a webhook URL configured
Webhook Delivery Logs
Currently, webhook delivery logs are not exposed in the API. Contact support if you need assistance troubleshooting webhook delivery issues.
Timeout Issues
Webhook requests have a 10-second timeout. If your endpoint takes longer than 10 seconds to respond, the request will fail. Process webhooks asynchronously:
Best Practices
- Idempotency: Handle duplicate webhook deliveries gracefully
- Async Processing: Respond quickly, process slowly
- Error Logging: Log all webhook errors for debugging
- Monitoring: Set up alerts for webhook failures
- Validation: Always validate the payload structure
- Security: Verify requests and use HTTPS
Webhook Behavior
Webhook Specifications
| Name | Type | Required | Description |
|---|---|---|---|
| Trigger Event | info | Optional | Document status changes to COMPLETED |
| Retry Policy | info | Optional | No automatic retries |
| Timeout | info | Optional | 10 seconds |
| Method | info | Optional | HTTP POST |
| Content-Type | info | Optional | application/json |
| User-Agent | info | Optional | QuickSign-API/1.0 |