Events will be POSTed to your callback URLs. There are two kinds of callbacks that can be defined:
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.
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.
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.
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.
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": { ... } }
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 |
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 |
signature_request_canceled | The SignatureRequest has been canceled. | SignatureRequest | App & account callbacks |
signature_request_prepared | The SignatureRequest has been prepared but not sent. | 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 while processing a signature request. | 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 |
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= |
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_CREATE_API_KEY_FIRST. It can also be found on the settings page.
Calculating event_hash
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 |