Web Hooks


Bulksign supports web hooks / callbacks to notify your integration when the envelope status is changing and when a recipient is performing a specific action.

Info
  • SAAS version supports callbacks using web requests
  • On-Premise version supports out of the box providers for sending the callbacks using : web requests, named pipes or RabbitMQ . You can also implement an extensibility provider to send this notification to your integration using a different way.

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 web requests, you need to set a URL value to enable global callbacks (the presence of a URL indicates that global callbacks are enabled). Also envelope status and recipient action callbacks can be enabled independent one of another.

  • per individual 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 event 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 : sent when the envelope is completed

Canceled : sent when the envelope is canceled by the sender

Expired : sent when the envelope is expired

Deleted : sent when the envelope is deleted by the sender

Restarted : sent when an expired envelope is restarted by the sender

Unlocked : sent when a envelope with parallel recipients unlocks signing (either manually by the sender or automatically).

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.

SignedField : sent when a signature field (or multiple in case of batch signing) gets signed.

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