Web Hooks


Bulksign supports web hooks / callbacks (using HTTP(S) for SAAS version and HTTP(S)/named pipes/RabbitMQ and custom for private versions) to notify the envelope sender when the status is changing and when a recipient is performing a specific action.

WebHooks can be set like this :

  • global : will apply to ALL envelopes. Set them from UI, log in as Bulksign and navigate to Settings \ WebHooks.
Info

Even if callbacks are not sent using HTTP(S), you need to set a URL value to enable global callbacks.

  • per envelope : from API when calling SendEnvelope, you can set the web hooks URLs like this :
OverwriteCallbackUrls
{
    CallbackEnvelopeStatusChangedUrl = "http://localhost/mysite?id={{#id#}}&status={{#status#}}&email={{#senderEmail#}}",
    CallbackRecipientActionUrl = "https://myendpoint.com/callback?email={{#email#}}&recipientStatus={{#action#}}&id={{#id#}}"
}

Envelope Status

The following envelope statuses are supported :

Created : this is sent ONLY for envelopes created in incognito mode. Option "Send callback when envelope is created by user in incognito mode" must be enabled in Settings\WebHooks

Completed

Canceled

Expired

Deleted

The following URL parameters are usable :

  • {{#id#}} : this will be replaced with the id of the envelope for which the callback is called.
  • {{#status#}} : this will be replaced with the envelope status value.
  • {{#senderEmail#}} : this will be replaced with the envelope sender's email.
Info

Please note the the names of placeholder parameters are case sensitive


Recipient Action

Callbacks are also supported for the following recipient actions :

Opened : sent when a signer opened the document for the first time (this is only sent once)

Finished : recipient has signed all assigned signature fields and finished the document.

Rejected : recipient has rejected to sign the document.

NextSigner : only sent for serial envelope, it's triggered when a new recipient has to sign.

Delegated : sent when recipient has delegated signing.

Authenticated : sent when recipient has successfully authenticated and accessed the signing document.

EmailError : sent when the signing email sent to a signer/approver recipient bounced and cannot be delivered successfully.

IdentityVerificationSubmitted : sent when the signer submitted the identity verification data.

IdentityVerificationAccepted : sent when the envelope sender accepted the identity verification data.

IdentityVerificationRejected : sent when the envelope sender accepted the identity verification data.

OTPSent : sent when a OTP is sent by SMS to the signer.

Read : sent when the user confirms reading the document

AuthenticationFailed : sent each time when the user authentication fails.


The following URL parameters are usable :

  • {{#email#}} : recipient email
  • {{#action#}} : recipient action value
  • {{#id#}} : envelope id
  • {{#senderEmail#}} : envelope sender email
Info

Please note the the names of placeholder parameters are case sensitive.


View Sent Callbacks

It's possible to see the list of sent callbacks in the Bulksign UI. Navigate to the envelope details page, click the "info" button (top right side of the page) and click the "Callbacks" button. You will be redirected to a page which shows all callbacks sent so far for that specific envelope (timestamp and the received HTTP status code is also included).
As a Bulksign administrator, you can also see the list of sent callbacks for a specific envelope from Settings \ Envelope Information.


Important!

Please note that callbacks are sent independently. If retries are enabled, a single callback will be retried until Bulksign receives a positive response from the callback handler. A callback cannot be "canceled" by a different callback.


Trigger callbacks multiple times

If you cannot implement an integration that stores the id of the sent envelopes and relies and callbacks + polling for getting the envelope status, it's also possible to configure Bulksign to sent the callback multiple times (in case your callback handler goes down and you are missing the first request).

The settings are : 

    "CallbackSettings" : {
            "TriggerMultipleTimes" : "true",
            "DelayInMinutes" : 10
    }

DelayInMinutes represents the time between each request. The minimum value which can be configured is 5 minutes. The maximum number of times the callback is triggered is based on the value configured in "JobMaximumRetries".

If you enable multiple triggers and using web hooks , please make sure you return the 200/202 (which means a successful result) as soon as possible. If you delay the HTTP 200 response the web request might time out and callback will be sent again. The timeout value for the request can be configured at :

 "EnvelopeStatusCallbackProviderType.HttpEnvelopeStatusCallbackProvider.TimeoutSeconds": "10",
 "RecipientActionCallbackProviderType.HttpRecipientActionCallbackProvider.TimeoutSeconds": "10",
Important!

We offer a sample integration project on Github which can be used by anyone which integrates Bulksign