3. Webhooks
Webhooks Overview
Webhooks provide a powerful mechanism for receiving real-time notifications about document events in the Circularo system. They enable seamless integration with your existing systems and workflows, allowing your applications to respond immediately to changes without the need for constant polling.
Understanding Webhooks
Webhooks are HTTP callbacks that notify your systems when specific events occur in Circularo:
Real-time Notifications: Receive immediate updates when documents are created, signed, or completed
Push-based Architecture: Events are pushed to your system as they happen, eliminating the need for polling
Standardized Format: All webhook notifications follow a consistent JSON structure for easy processing
Secure Communication: Optional HMAC signature verification ensures the authenticity of webhook requests
Key Webhook Concepts
Understanding these fundamental concepts will help you implement webhooks effectively:
Webhook Registration: Creating webhooks to specify where notifications should be sent
Callback URLs: Publicly accessible endpoints that receive webhook notifications
Event Types: Different types of document events that trigger webhook notifications
Webhook Scope: Organization-level or tenant-level coverage of document events
HMAC Verification: Cryptographic method to verify the authenticity of webhook requests
Business Benefits
Implementing webhooks in your integration provides significant advantages:
Improved Responsiveness: React to document events in real-time without delay
Reduced API Load: Eliminate the need for frequent polling, reducing system load and API usage
Workflow Automation: Trigger automated processes when specific document events occur
System Integration: Connect Circularo with your CRM, ERP, or other business systems
Enhanced User Experience: Provide immediate feedback to users when document status changes
Webhook endpoints must be publicly accessible and capable of receiving HTTP POST requests. Ensure your endpoint is properly secured and can handle the expected volume of notifications.
Common Webhook Events
Webhooks can notify your system about various document events, including:
documentCreated: A new document has been created in the system
signRequest: A document has been shared with recipients for signing
documentSigned: A document has been signed by a user
documentCompleted: All required signatures have been collected for a document
signRejected: A recipient has rejected the document signing request
documentDeleted: A document has been deleted from the system
Webhook Security
Securing webhook communications is essential for maintaining the integrity of your system:
HMAC Signature Verification: Verify the authenticity of webhook requests using SHA-256 signatures
Secret Management: Securely store and manage webhook HMAC secrets
Request Validation: Validate the structure and content of webhook requests before processing
Error Handling: Implement proper error handling for webhook processing failures
When using HMAC verification, each webhook request includes an `x-circularo-signature` header containing a SHA-256 HMAC signature of the request body. Your server should verify this signature to ensure the request is authentic.
Webhook Implementation Best Practices
Follow these best practices for a robust webhook implementation:
Respond Quickly: Always respond to webhook requests promptly (within seconds) to prevent timeouts
Process Asynchronously: For time-consuming operations, acknowledge the webhook immediately and process the data in the background
Implement Retry Logic: Be prepared to handle temporary failures in your webhook processing
Monitor Webhook Activity: Log webhook events and set up alerts for unusual patterns or failures
Getting Started
The scenarios in this section provide comprehensive guidance on implementing webhooks:
Begin with webhook management to learn how to create, retrieve, and delete webhooks
Explore webhook consumption to understand how to receive and process webhook notifications
Learn about webhook security and how to verify the authenticity of webhook requests
Discover best practices for implementing robust webhook receivers in various programming languages