Introduction
APIs are sets of rules and protocols for software applications to interact with each other. A webhook is a method of communication between systems that is event-driven. Unlike an API, which requires an application to make requests actively to retrieve data or perform actions, a webhook automatically sends data to another system when a specific event occurs.
This blog post will explore why webhooks are important in API integration, focusing on their use in the BoldSign eSignature platform.
Why webhooks?
Webhooks remove the need for continuous polling by automatically sending data to your application when a specific event occurs. This means your application no longer has to check frequently for updates, reducing the load on both the client and server.
Applications struggle without webhooks
In the absence of webhooks, applications are forced to rely on frequent polling to check for updates or changes. This requires the application to send requests to the server continuously, asking if there’s any new data or events that need attention. Polling is resource-intensive for both the client (your application) and the server, leading to increased load, slower performance, and the potential for hitting API rate limits, which can block critical operations when they are needed most.
Moreover, developers must write and maintain complex code to manage polling, error handling, and retries. This adds to the development burden, making the application harder to manage over time.
For applications in which users expect immediate feedback, the absence of webhooks can significantly degrade the user experience. For instance, if a user completes an action and expects a real-time notification or update, the delays inherent in polling can cause frustration and dissatisfaction.
How BoldSign utilizes webhooks
BoldSign uses webhooks to deliver real-time notifications.
App-level webhooks
App-level webhooks are triggered by events related to documents sent through a specific OAuth app. This setup is good for developers who need to monitor activities within a particular application in their BoldSign integration.
Account-level webhooks
Account-level webhooks are triggered by events for documents sent from either the BoldSign web app or API. This broader setup allows you to monitor all activities across an entire account, providing immediate notifications of document status changes.
Available events
BoldSign offers many events that can trigger webhooks, ensuring you stay informed about every step in your eSignature process:
- Sent: Triggered when a signature request is sent to recipients.
- Signed: Occurs when a document is signed by a recipient.
- Completed: Indicates the completion of the signing process for a document.
- Edited: Triggered when a document is edited.
- Declined: Occurs when a signature request is declined by a recipient.
- Revoked: Occurs when a signature request is revoked by the sender.
- Reassigned: Triggered when a signer reassigns a document.
- Expired: Indicates that the signature request has expired.
- Viewed: Triggered when a document is viewed by any of the recipients.
- Authentication Failed: Occurs when a signer’s authentication attempt to access a document fails.
- Delivery Failed: Triggered when email delivery fails for any recipients in a signature request.
- Send Failed: Occurs when a signature request fails to send.
- Draft Created: Triggered when a draft document is created.
- Remind Document: Occurs when a signature request reminder email is sent by the sender.
- Sender Identity Events: Various events related to sender identity creation, updates, and verification.
- Template Events: Triggered when templates are created, edited, or fail to send.
- Identity Verification Events: Various events related to the initiation, success, or failure of identity verification.
Refer to this documentation to learn more about all the available events in BoldSign.
Maximum response time
The application should respond to an HTTP POST request within 10 seconds with a 200 status code. Failure to respond within this timeframe will initiate a retry mechanism.
Retry mechanism
BoldSign’s robust retry mechanism ensures reliable delivery of webhook events, even if your server is temporarily unavailable. The retry schedule is as follows:
| Attempts | Retry |
|---|---|
| 1 | 1 minute |
| 2 | 15 minute |
| 3 | 45 minute |
| 4 | 1 hour |
| 5 | 8 hours |
| 6 | 24 hours |
If the endpoint does not respond with a 200 OK for all six attempts, the webhook is marked for disabling. However, BoldSign provides an auto-recovery mechanism, allowing webhooks to resume normal operation if the endpoint starts responding within 7 days.
Refer to this documentation to set up webhooks in your account.
Best practices for using webhooks
To ensure reliable and efficient webhook integration, consider the following best practices:
- Timely Responses: Respond quickly to webhook requests to avoid failures. Consider processing the request asynchronously to ensure a prompt response.
- Handle Duplicate Events: Implement checks to avoid processing duplicate events with the same event ID.
- Monitor Webhook Performance: Use logging and monitoring tools to track webhook activity and troubleshoot any issues.
- Manual Resend: Use the manual resend feature to test endpoints during development and handle specific scenarios.
Conclusion
Webhooks are an essential part of efficient API integration, providing real-time updates and reducing resource usage. By implementing webhooks, BoldSign enhances the eSignature experience, providing timely notifications and seamless integration with other systems. Incorporating webhooks into your API workflows can significantly improve the efficiency and responsiveness of your applications, making it easier for both developers and users.
We value your feedback. Post your suggestions in the comments section below. Our dedicated support team is available to assist you, whether you have questions, recommendations, or want to learn more about what BoldSign has to offer. Schedule a call for a customized demo or contact us through our support portal.
