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:

SentWhen a signature request is sent to recipients.
SignedWhen a document is signed by a recipient.
CompletedWhen the signing process is completed for a document.
DeclinedWhen a signature request is declined by a recipient.
RevokedWhen a signature request is revoked by the sender.
ReassignedWhen a signer reassigns a document.
ExpiredWhen the signature request has expired.
ViewedWhen a document is viewed by any of the recipients.
Authentication failedWhen a signer's authentication to sign a document fails.
Delivery failedWhen email delivery is failed for any of the recipients in a signature request.
Send failedWhen a signature request is failed to send.
Draft createdWhen a draft document is created.
Sender Identity CreatedWhen a sender identity is created successfully.
Sender Identity UpdatedWhen a user updates/re-requests the sender identity.
Sender Identity DeletedWhen a user deletes the sender identity.
Sender Identity RevokedWhen a sender identity revokes the permission to send documents on their behalf.
Sender Identity VerifiedWhen a sender identity accepts the invitation.
Sender Identity DeniedWhen a sender identity rejects invitation.
Template createdWhen a template is created.
Template create failedWhen a template create is failed.
Template Draft createdWhen a draft template is created.
Identity Verification InitiatedWhen identity verification process is initiated by the signer.
Identity Verification SucceededWhen the identity verification process succeeds.
Identity Verification FailedWhen the identity verification process fails.

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 attempt1 minute
2nd attempt15 minutes
3rd attempt45 minutes
4th attempt1 hour
5th attempt8 hours
6th attempt24 hours

Auto disable

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.

Webhook is marked for disabling

Webhook is marked for disabling - overview

Auto recovery

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.

Email notifications

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.

Re-enable the inactive webhooks

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.

Re-enable disabled webhook

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.

OAuth app

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:

OAuth save

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.

Create webhook

Choose a call back as APPs level.

Select AP Ps level

In the application drop-down menu, select the application you just created in the OAuth Apps section.

Select application

You can provide a webhook name. It will be useful for our personal identification and the purpose of a webhook to keep things organized.

Webhook name

You need to provide a webhook URL, to which BoldSign will send notifications when an event happens in your document. HTTPS URLs are required.

Https url

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.

Click verify button

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.

URL verification

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.

Trigger events

Once you have completed all the above steps, click Save and create a webhook, as follows.

Submit form

Account level webhook

Go to the webhooks page under the API section and click the Add Webhook button at the top right corner.

Create webhook

Choose a call back as Account level

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.

Account name

You need to provide a webhook URL, to which BoldSign will send notifications when an event happens in your document. HTTPS URLs are required.

Verify account url

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.

Verified url

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.

Verified url

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.

Trigger events

Once you have completed all the above steps, click Save and create a webhook, as shown in the following image.

Submit account level

Admin Mode

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.

Admin mode

Manually resend events

The automatic retry mechanism will resend the event on a fixed schedule with increasing exponential backoff. However, there may be a need to manually resend the event for various reasons or to test the endpoint during development to ensure it is working as expected. You can manually resend the event by clicking the 'Retry' button on the webhook history page.

Both successful and failed events can be resent manually. The event will be resent immediately when you click the 'Retry' button.

Webhook event resend

When an event is successfully resent, it will be marked as successful with an icon for the existing failed event.