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

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.

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

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 below:

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 to 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 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.

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.

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

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

Choose to call back as APPs 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 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.

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.

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