Triggered when a document transitions between different states in its lifecycle.

Document States

Common document state transitions include:

Creation & Sending

• document.draft - Document creation and processing is complete
• document.sent - Document has been sent to recipients
• document.viewed - Document has been opened by a recipient

Approval Workflow

• document.waiting_approval - Document is pending approval workflow
• document.approved - Document has been approved
• document.rejected - Document has been rejected

Payment Processing

• document.waiting_pay - Document is pending payment
• document.paid - Document payment has been completed

Completion

• document.completed - Document has been fully signed/completed
• document.cancelled - Document has been cancelled
• document.declined - Document has been declined by a recipient

Use Cases

This webhook is ideal for:

• Process Automation - Trigger business workflows based on document state
• System Integration - Synchronize document status with external systems
• Workflow Management - Implement approval processes and notifications
• Analytics & Reporting - Track document completion metrics
• Real-time Monitoring - Monitor document lifecycle changes

Important Considerations

Recipient Shared Links

⚠️

Known Limitation: The shared_link field in the recipients array may be empty in webhook payloads due to asynchronous processing.

Recommended Solution: Use the Document Details API endpoint (GET /public/v1/documents/{id}/details) to retrieve complete recipient information when shared_link is needed.

Payload Structure

📝

Note: The webhook payload structure mirrors the Document Details API response, providing comprehensive document information at the time of state change.

default_date_format on data is primarily used when data.status is document.sent or document.completed; it may be absent or null for other statuses or if the workspace setting is unavailable.

Security

🔒

Security: All webhook requests include an HMAC-SHA256 signature for verification using your shared key.