Meet our new brand: eversign is now Xodo Sign! Learn more


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 Xodo Sign 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 Xodo Sign control panel, embedded flows and documents sent via the Xodo Sign 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 Xodo Sign 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": "", "role": "", "order": "1" } }

Event Callback Object:

Here's a complete table of all the different objects that can be contained inside an Xodo Sign 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. The signer ID this event is associated with. The name of the signer this event is associated with. 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 Xodo Sign event, your endpoint must return an HTTP 200 status code indicating that the event has been successfully received. Webhooks are automatically retried for up to 24 hours if no HTTP 200 status code is returned.

Ensure you return the HTTP 200 status code as early as possible to prevent the connection timeout.

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.
document_forwarded The document has been forwarded 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.
document_expired The document has expired without being signed by all required signers.
document_revoked The document has been canceled by the owner.
document_cancelled This event is triggered automatically after events that lead to document cancellation such as document_revoked or signer_bounced.
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 ยป