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.

The app level webhook will trigger events only to the document sent using the OAuth app.

The account level webhook will trigger events to the document sent from the web app or API.

The following mentioned events will trigger a callback to the configured webhook URL when triggered by you or your user's account:

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.

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:

If your endpoint does not respond with a 200 OK for all six attempts, the system will start analyzing the history of failures associated with the failing webhook. If your webhook endpoint has not responded with a 200 OK for even a single webhook request in the past few days, it will trigger a disable mechanism, and the webhook will be scheduled to be disabled after 7 days.

The system will continue to send webhook events for the next 7 days once scheduled for disable. If the system detects that your webhook endpoint starts responding with a 200 OK for the webhook request during these 7 days, it will consider the webhook as recovered. It will cancel the disabling process and continue to send webhook events as normal.

BoldSign will send email notifications throughout the webhook lifecycle to the creator of the webhook. The system will send emails for the following cases:

• When your webhook is scheduled for disable due to continuous failure.
• An alert email 24 hours before executing the disable process.
• When your webhook is disabled as scheduled.
• When your webhook is automatically recovered.

You can re-enable the auto-disabled webhook from the webhook dashboard page. The page will list all the webhooks that were created in your account, and you can re-enable the inactive webhooks.

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.

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.

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.

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.

The admin model allow the admins to subscribe and listen for the events from their team members. The account admin can subscribe to the events that happen in their organization level and the team admin can subscribe to the events that happen in their team level. This will be particularly useful in automation apps such as zapier, power automate, etc. to listen to the events that happen in their organization or team level.

This option can be enabled by selecting the 'Admin Mode' checkbox in the webhook creation modal.