Events and Callbacks
Introduction

Events will be POSTed to your callback URLs. There are two kinds of callbacks that can be defined:

Account Callbacks

This type of callback URL can be set up at the account level (either by setting it through an API request to "/v3/account" or on the Account Settings page on hellosign.com).

All signature request events that involve your account are reported to this URL. This includes events such as receiving a signature request, or when a signature request you've sent is signed by someone. Events are reported to the account callback URL for either requests originating on hellosign.com, or on a partner site, via an embedded flow.

You can set your account callback by using the account API call or manually on the settings page.

App Callbacks

This type of callback URL is set up at the API app level. API apps are used to identify a partner integration and configure embedded flows (embedded signing, embedded requesting, and embedded templates) and OAuth providers.

All events that involve signature requests created by an API app are reported to this URL. The event will include a client_id field to indicate which app the event is being reported for, which allows multiple API apps to share the same callback URL.

You can manage your apps and their callbacks from the settings page.

Callback Response Format

The default format for messages sent to your callbacks is a multipart ('form/multipart') POST request, with the message details in a POST field named 'json'.

The Java SDK includes an event parsing class, and you can access this field in the $_POST array on PHP. For other platforms, either a library function, such as cgi.parse_multipart (for python) or ActionDispatch::Http::UploadedFile for Rails, or third party options, such as multer for node, may be useful.

Responding to callbacks

Your endpoint will need to return a 200 HTTP code and a response body containing the following text: Hello API Event Received. Otherwise, the callback will be considered a failure and will be retried later.

The Event Object

Events posted to your callback url will be formatted as a JSON string contained in the json POST param. The complete detail for the event object can be found in the event section of the API reference page. Here is an example of an event that could be received:

{
    "account_guid": "63522885f9261e2b04eea043933ee7313eb674fd", // DEPRECATED: use reported_for_account_id instead
    "client_id": null,  // DEPRECATED: use reported_for_app_id instead
    "event": {
        "event_time": "1348177752", 
        "event_type": "signature_request_sent",
        "event_hash": "3a31324d1919d7cdc849ff407adf38fc01e01107d9400b028ff8c892469ca947",
        "event_metadata": {
            "related_signature_id": "ad4d8a769b555fa5ef38691465d426682bf2c992", 
            "reported_for_account_id": "63522885f9261e2b04eea043933ee7313eb674fd",
            "reported_for_app_id": null
        }
    }, 
    "signature_request": {
        ...
    }
}
Types of events

The following table details all the possible values for event_type.

Event Type Description Attached Model Reported to
signature_request_viewed The SignatureRequest has been viewed. SignatureRequest App & account callbacks
signature_request_signed A signer has completed all required fields on the SignatureRequest. SignatureRequest App & account callbacks
signature_request_downloadable An updated version of the SignatureRequest PDF is available for download. SignatureRequest App & account callbacks
signature_request_sent The SignatureRequest has been sent successfully. SignatureRequest App & account callbacks
signature_request_declined The SignatureRequest was declined by a signer. SignatureRequest App & account callbacks
signature_request_reassigned The signer has reassigned their signature to a different signer. SignatureRequest App & account callbacks
signature_request_remind All signers have been sent a reminder to complete the SignatureRequest. SignatureRequest App & account callbacks
signature_request_all_signed All signers have completed all required fields for the SignatureRequest and the final PDF is ready to be downloaded using signature_request/files. SignatureRequest App & account callbacks
file_error We're unable to convert the file you provided. SignatureRequest App & account callbacks
unknown_error An unknown error occurred during while processing a signature request. SignatureRequest App & account callbacks
signature_request_email_bounce An email address for one of the signers on your signature request has bounced. May be correctable by using signature_request/update. SignatureRequest App & account callbacks
signature_request_invalid An error occurred while processing the signature request data on our back-end.

For example: Invalid text tags
SignatureRequest App & account callbacks
sign_url_invalid The embedded sign URL you provided is invalid or expired. SignatureRequest App & account callbacks
account_confirmed An account created via one of your apps has been confirmed. Account App callbacks only
template_created The Template has been created. Template App & account callbacks
template_error There was an error while creating your template. Template App & account callbacks
Callback HTTP headers

We provide a couple of headers on callback requests to help you identify them.

Name Description Value
User-Agent A token identifying us HelloSign API
Content-MD5 A base64 encoded MD5 signature of the request's JSON payload, generated using your API key.
base64_encode(hash_hmac('md5', $json, $api_key))
Example value: NTc3MTlkMDA3MDE5NzNmNmYzZWVmZWNlOWM1MTZlZWE=
Event Hash Verification

Each event object in the callbacks contains an event_hash to help you verify that it's really coming from HelloSign. The event_hash is generated with the HMAC algorithm using your API Key as a key and SHA256 digest mode.

Your API Key is SIGN_IN_AND_CONFIRM_EMAIL_TO_SEE_YOUR_API_KEY_HERE. It can also be found on the settings page.

Calculating event_hash

Failure and Retries

If your callback url is not reachable or returns a non-successful response, we will retry POSTing the event up to 6 times, with each retry interval being exponentially longer than the previous one. If the sixth retry fails, we will clear your callback url and you must enter a new one to receive future callback events.

Please note that our requests will timeout after 30 seconds, so callbacks will fail if your server takes longer than that to respond. The retry pattern is described below, an alert email will be sent to you after POSTing has failed several times.

Retry Delay after previous attempt
First 5 minutes
Second 15 minutes
Third 45 minutes
Fourth 2 hours 15 minutes
Fifth 6 hours 45 minutes
Sixth 20 hours 15 minutes