Webhooks

There are two types of event callbacks that can be posted to the Webhook URLs you specify: Account-based callbacks and App-based callbacks.

Account-based Callbacks

Account-based callbacks can be activated by logging in to your eversign account, navigating to the Developer page using the top left dropdown menu and entering your preferred callback URL in the "Webhook URL" section.

Once set up, all document events related to your documents across all of your businesses will be reported to this URL. This includes events triggered manually using the eversign control panel, embedded flows and documents sent via the eversign API.


App-based Callbacks

You can also specify a Webhook URL for each of your registered apps either during creation of your app or by editing it accordingly. To register or edit an app, please log in to your eversign account and navigate to the Developer page.

If a Webhook URL is specified for an individual app, all document events related to documents created using this app will be reported to this URL.


Callback Format

Callback messages are sent as POST requests with a JSON body. Below you'll see an example callback message sent when a document was created.

Example Callback Body:

{ "event_time": "1509020237", "event_type": "document_sent", "event_hash": "6f5860af92e41d3bf5885054b02a88afb31550d93d2c5859041bd9dc0f8f2967", "meta": { "related_document_hash": "uXIgmUwHpeFqjI", "related_user_id": "40211", "related_business_id": "267", "related_app_id": "" }, "signer": { "id": "1", "name": "Paul McSign", "email": "paul@zehetmayr.com", "role": "", "order": "1" } }

Event Callback Object:

Here's a complete table of all the different objects that can be contained inside an eversign webhook:

Object Description
event_time The exact time (UNIX time stamp) the event occurred.
event_type The type of event that occurred.
event_hash The unique hash of the event that occurred.
meta.related_document_hash The unique document hash this event is associated with.
meta.related_user_id The user identification this event is associated with. (Sender User ID)
meta.related_business_id The business ID this event is associated with. (Sender Business ID)
meta.related_app_id If this event is sent as part of a webhook notification for a specific app, this will contain the associated App ID.
signer.id The signer ID this event is associated with.
signer.name The name of the signer this event is associated with.
signer.email The email address of the signer this event is associated with.
signer.role The role of the signer this event is associated with. (Templates only)
signer.order The signer order sequence number of the signer this event is associated with.

Handling Callbacks

When you receive an eversign event, your endpoint should return a HTTP 200 status code indicating that the event has been successfully received. Webhooks are autmatically retried for up to 24 hours if no HTTP 200 status code is returned.

Document Events:
The following events will be reported to your account-based or app-based Webhook URLs:

Event Description
document_created The document has been created.
document_viewed The document has been viewed by one of its signers.
document_sent The document has been sent to one of its signers.
document_signed The document has been signed by one of its signers.
document_declined The document has been declined by one of its signers.
signer_removed One of the document's signers has been removed.
signer_bounced The document could not be delivered to one of its signers.
document_completed The signing of the document has been completed.
email_validation_waived Email validation has been disabled for this document. (In-Person Signing or Embedded Signing has been enabled)

Validating Event Hashes

Each document event reported to your Webhook URL comes with an event_hash object containing a hash generated with the HMAC algorithm using your API Key as a key and SHA256 digest mode.

Here's how to calculate / validate an event hash: (PHP example)

hash_hmac("sha256", $event_time . $event_type, $your_api_key);

Don't know where to find your API Access Key? Find out here »