Webhooks

Table of contents

Getting Started

Create Document: Fields

Bulk Sending

Bulk Sending Process

Hidden Tags

Embedded Signing

Embedded Requesting

OAuth 2.0

Webhooks

Libraries

Stay up to date

Twitter(@geteversign)

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": "[email protected]",
    "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.
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 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