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 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": "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 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 ยป