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 events mentioned below will trigger 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 is 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.

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 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 attempt to deliver your webhooks until 48 hours in exponential order. The retry mechanism will be initiated, and the retry interval is mentioned below:

1st attempt1 minute
2nd attempt15 minutes
3rd attempt45 minutes
4th attempt1 hour
5th attempt8 hours
6th attempt24 hours

If your endpoint does not respond within 6 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 for 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 below:

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 to 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 an 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 below 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 10 seconds to be verified successfully. When the URL is successfully verified, you should see the acknowledgement like below in the modal.

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 like below.

submit form

Account level webhook

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

create webhook

Choose to call back as APPs 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 an 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 below 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 10 seconds to be verified successfully. When the URL is successfully verified, you can see the acknowledgement like below in the modal.

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 like below.

submit account level