Webhooks Introduction
Webhooks are automated HTTP callbacks, which is a way for an app to provide other applications with real-time information when a user-defined action is performed in a web application (in this case, BoldSign application).
You can configure to subscribe to any of the events associated with your BoldSign account. When one of the subscribed events is triggered, we will send an HTTP POST request with json data to the configured webhook URL.
We have APPs level and account level callbacks in our webhooks.
APPs level
The app level webhook will trigger events only to the document sent using the OAuth app.
Account level
The account level webhook will trigger events to the document sent from the web app or API.
Available events
The following mentioned events will trigger a callback to the configured webhook URL when triggered by you or your user's account:
Sent | When a signature request is sent to recipients. |
Signed | When a document is signed by a recipient. |
Completed | When the signing process is completed for a document. |
Declined | When a signature request is declined by a recipient. |
Revoked | When a signature request is revoked by the sender. |
Reassigned | When a signer reassigns a document. |
Expired | When the signature request has expired. |
Viewed | When a document is viewed by any of the recipients. |
Authentication failed | When a signer's authentication to sign a document fails. |
Delivery failed | When email delivery is failed for any of the recipients in a signature request. |
Send failed | When a signature request is failed to send. |
Draft created | When a draft document is created. |
Sender Identity Created | When a sender identity is created successfully. |
Sender Identity Updated | When a user updates/re-requests the sender identity. |
Sender Identity Deleted | When a user deletes the sender identity. |
Sender Identity Revoked | When a sender identity revokes the permission to send documents on their behalf. |
Sender Identity Verified | When a sender identity accepts the invitation. |
Sender Identity Denied | When a sender identity rejects invitation. |
Template created | When a template is created. |
Template create failed | When a template create is failed. |
Template Draft created | When a draft template is created. |
Maximum response time
When the HTTP POST request is made to the configured URL, the application should respond to the request within 10 seconds with a 200 status code. If failed to respond within the mentioned time limit, the POST request will be marked as failed, and the retry mechanism will be initiated.
Retry mechanism
When the listening endpoint is down, BoldSign will make multiple attempts to deliver your webhooks over a span of 48 hours in exponential order. The retry mechanism will be initiated, and the retry interval is mentioned as follows:
1st attempt | 1 minute |
2nd attempt | 15 minutes |
3rd attempt | 45 minutes |
4th attempt | 1 hour |
5th attempt | 8 hours |
6th attempt | 24 hours |
If your endpoint does not respond within six attempts, the webhook callback will be disabled and you will be notified via email. You need to create a new webhook to receive any future callback events if your existing webhook is disabled.
Handling duplicate events
Your webhook endpoint might occasionally receive duplicate events, so it is essential that your endpoint is resistant to these duplicate events. This can be avoided if you prevent processing events with the same event ID more than once.
Timely response to webhooks
The response to the webhooks should be done quickly to avoid failures. In order to respond within 10 seconds, you can respond back as soon as the request is received and carry on your process in a separate thread or asynchronously in your endpoint.
The webhook can be configured to trigger the lifecycle of a signature request for different actions based on your preference. You need to configure your web application endpoint to listen for these callbacks.
Setting up webhook in your account
App level webhook
To create an app level webhook, first, you need an OAuth application, to which the webhook will be tied. Go to the OAuth Apps page under the API section and click the Create Your First APP
button.
You can create a developer application in both Sandbox and Live mode. Once you have tested your webhook in Sandbox mode, you can choose Live mode to use it in your production. The option for creating the application can be toggled in the Create Application window, as shown in the following image:
Once you have created an OAuth application, you can use that application to create a webhook like below:
Go to the webhooks page under the API section and click the Add webhook
button at the top right corner.
Choose a call back as APPs level.
In the application drop-down menu, select the application you just created in the OAuth Apps section.
You can provide a webhook name. It will be useful for our personal identification and the purpose of a webhook to keep things organized.
You need to provide a webhook URL, to which BoldSign will send notifications when an event happens in your document. HTTPS URLs are required.
Once you have provided a URL, it needs to be verified to successfully register as a valid webhook. To verify a webhook, simply click the Verify
button beside the URL textbox.
When you click the Verify
button, an HTTP POST request will be sent to your URL with the following JSON payload. The eventType
property value is Verification.
{ "event": { "id": "7c872a5b-xxxx-xxxx-xxxx-92530a83a8b9", "created": 1617180024, "eventType": "Verification", "clientId": "17c97f7a-xxxx-xxxx-xxxx-fef97b6544a7", "environment": "Test" } }
NOTE: Your endpoint needs to respond with HTTP status code 200 OK within a time frame of 10 seconds to be verified successfully. When the URL is successfully verified, you should see the acknowledgment in the modal, as shown in the following image.
You can specify your actual endpoint URL instead of ngrok created URL if you have already set up your endpoint to receive callbacks. You can subscribe and listen to individual events or all the events that happen in a document from a webhook.
Once you have completed all the above steps, click Save
and create a webhook, as follows.
Account level webhook
Go to the webhooks page under the API section and click the Add Webhook
button at the top right corner.
Choose a call back as Account level
You can provide a webhook name. It will be useful for our personal identification and the purpose of a webhook to keep things organized.
You need to provide a webhook URL, to which BoldSign will send notifications when an event happens in your document. HTTPS URLs are required.
Once you have provided a URL, it needs to be verified to successfully register as a valid webhook. To verify a webhook, simply click the Verify
button beside the URL textbox.
When you click the Verify
button, an HTTP POST request will be sent to your URL with the following JSON payload. The eventType
property value is Verification.
{ "event": { "id": "7c872a5b-xxxx-xxxx-xxxx-92530a83a8b9", "created": 1617180024, "eventType": "Verification", "environment": "Test" } }
NOTE: Your endpoint needs to respond with HTTP status code 200 OK within a time frame of 10 seconds to be verified successfully. When the URL is successfully verified, you can see the acknowledgment in the modal, as shown in the following image.
You can specify your actual endpoint URL instead of ngrok created URL if you have already set up your endpoint to receive callbacks. You can subscribe and listen to individual events or all the events that happen in a document from a webhook.
Once you have completed all the above steps, click Save
and create a webhook, as shown in the following image.