Document State Changed Webhook

wbhk Document State Changed

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.