5. Webhooks - signeasy/API GitHub Wiki
Webhooks allow you to build or set up applications which subscribe to certain events associated with your SignEasy account. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Webhooks can be used to update your internal or external dashboards, trigger sales workflows, update a document archive, or even trigger a 3rd party workflow. You're only limited by your imagination.
Types of webhooks
1. App level webhooks
You can use app level webhooks to be notified of events originating from only your app. This is useful if you want to be notified of document activity that was initiated from your integration/app. If you want to be notified about users that were created through your app, use app level webhooks.
To start receiving callbacks for your app level webhooks, all you would have to do is add a custom header in the API call. This header acts as a flag to turn on the callback to your webhooks. If you would like to selectively subscribe to events of a few users, you can choose to include the header for only those users.
Callback Header: Include this header to trigger callbacks to your app level webhook.
X-Client-ID : 5igAbZSN2rIdsfMJ0dv8QTSF1ZwSWRtefq5sdfl (your client ID)
Setting the app level webhook is currently under beta. Please reach out to [email protected] if you want this configured.
2. Global webhooks
Global webhook URLs receive events from all sources (SignEasy web and mobile apps, integrations on 3rd party sites like Zoho & Outlook and even custom integrations). These webhooks can be used to set up automated workflows, eg. exporting all your signed & completed documents to Dropbox or to trigger SMS notifications to your document signers upon signature request initiation or to be used with tools like Zapier & IFTTT.
You will be able to set a global webhook URL for any user through our APIs. Once set, you need not have to take anymore action, as and when there is new events for that user your webhooks will receive the callbacks immediately.
The API to configure the global webhook URL for a user is currently under beta and limited access. Please contact [email protected] with details of your use case, to start using the API or to configure the URL.
Events
The following events trigger a callback to the webhook you have configured for your or your users account.
Account creation events
| Event name | Description |
|---|---|
| account.created | Any time a new user account is created through your app |
| account.activated | When a user account created through your app, verifies their email address |
Self signed document events
| Event name | Description |
|---|---|
| document.signed | Any time a user self signs a document |
Request Signature events
| Event name | Description |
|---|---|
| rs.initiated | Any time a new signature request is initiated by the user |
| rs.link_sent | When the signers of the signature request receive their link to sign the document |
| rs.viewed | Any time a signer views the document they have been asked to sign |
| rs.signed | When a signer signs the document |
| rs.declined | When a signer declines to sign the document |
| rs.voided | When the user voids the signature request of a document |
| rs.reminded | When the user sends a reminder to the signers of the document |
| rs.completed | When all the signers of the document have completed signing |
Payloads
Each event type has a specific payload format with the relevant event information.
In addition to the fields documented for each event, webhook payloads include the user who performed the event (event_user), and for a app webhook may include the ID of the client (client_id) which an event relates to. An example is given in the account.created payload.
Account created
Triggered when a new user account is created by your app. This event can help you kickstart any user related workflows you may have in your system.
{
"data":{
"user_id":13
},
"metadata":{
"event_user":"[email protected]",
"event_type":"account.created",
"client_id":"teFUvfMU7UZb95ICJNxQ3HQ1L4XZ4tfVwvIZ9m1s"
}
}
Account activated
This event is triggered upon successful email verification of the account created through your app. You can then start making API calls on behalf of this user.
{
"data":{
"owner_user_id":2
},
"metadata":{
"event_type":"account.created",
"event_user_id":2,
"client_id":"6xkfd7cC9TEcXPOy1jxbHg9k8O8IpmQRAt7AWrTm",
"event_user":"[email protected]"
}
}
Self Signed Document
This event is triggered every time the user signs a document by themselves (includes self signing and in-person signing). This event can be used to export the signed document to any cloud storage service (Dropbox, Google Drive) or your custom document archival solution.
Use the id and the signed document download API to fetch the completed document.
{
"data":{
"pending_file":null,
"user_id":716389,
"name":"hello_05_Sep_2017-134723.pdf",
"checksum":"eaae8847ba4b579f0c404cc51ea4aa0a2b4cc828099ead9c8ff9c68f0abd4e38",
"created_time":1504619243,
"last_modified_time":1504619243,
"id":1105575
},
"metadata":{
"event_user":"[email protected]",
"event_type":"document.signed",
"client_id":null
}
}
Request Signature initiated
This event is fired when a new signature requested is initiated by your users. The payload will contains the details of the signers, document and the order of signing thereby helping you update any workflows on your end.
{
"data":{
"status":"incomplete",
"owner_first_name":"Jack",
"name":"Try it now - demo.pdf",
"recipients":[
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":1,
"last_modified_time":1505464109,
"recipient_user_id":2,
"recipient_id":7,
"created_time":1505464109,
"email":"[email protected]"
},
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":2,
"last_modified_time":1505464109,
"recipient_user_id":3,
"recipient_id":8,
"created_time":1505464109,
"email":"[email protected]"
}
],
"owner_email":"[email protected]",
"owner_last_name":"Barb",
"next":7,
"created_time":1505464109,
"last_modified_time":1505464109,
"has_markers":0,
"is_ordered":0,
"id":4,
"owner_user_id":1
},
"metadata":{
"event_type":"rs.initiated",
"event_user_id":1,
"client_id":"6xkfd7cC9TEcXPOy1jxbHg9k8O8IpmQRAt7AWrTm",
"event_user":"[email protected]"
}
}
Signers notified about the signature request
This event is fired whenever any signer of a signature request receives the link to sign the document. In case of parallel signing (un-ordered signing) you will receive the events for each signer individually.
{
"data":{
"status":"incomplete",
"owner_first_name":"Jack",
"name":"Try it now - demo.pdf",
"recipients":[
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":1,
"last_modified_time":1505462028,
"recipient_user_id":2,
"recipient_id":3,
"created_time":1505462028,
"email":"[email protected]"
},
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":2,
"last_modified_time":1505462028,
"recipient_user_id":3,
"recipient_id":4,
"created_time":1505462028,
"email":"[email protected]"
}
],
"owner_email":"[email protected]",
"owner_last_name":"Barb",
"next":3,
"created_time":1505462028,
"last_modified_time":1505462028,
"has_markers":0,
"is_ordered":0,
"id":2,
"owner_user_id":1
},
"metadata":{
"event_type":"rs.link_sent",
"event_user_id":2,
"client_id":null,
"event_user":"[email protected]"
}
}
RS signer viewed
This event is fired every time a signer views the document they were requested to sign. The payload contains details of who the signer is, time of viewing and the current status of their signature request.
{
"data":{
"status":"incomplete",
"owner_first_name":"Jack",
"name":"Try it now - demo.pdf",
"recipients":[
{
"status":"viewed",
"first_name":"",
"last_name":"",
"order_id":1,
"last_modified_time":1505462535,
"recipient_user_id":2,
"recipient_id":5,
"created_time":1505462478,
"email":"[email protected]"
},
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":2,
"last_modified_time":1505462478,
"recipient_user_id":3,
"recipient_id":6,
"created_time":1505462478,
"email":"[email protected]"
}
],
"owner_email":"[email protected]",
"owner_last_name":"Barb",
"next":5,
"created_time":1505462478,
"last_modified_time":1505462478,
"has_markers":0,
"is_ordered":0,
"id":3,
"owner_user_id":1
},
"metadata":{
"event_type":"rs.viewed",
"event_user_id":2,
"client_id":null,
"event_user":"[email protected]"
}
}
Signer signed the document
This event is fired when a signers signs the document they received. The payload contains details of who the signer is, time of signing and the current status of the signature request. Note that, this event is only an indicator that the signer has signed the document and not that the signature request is complete.
{
"data":{
"status":"incomplete",
"owner_first_name":"Jack",
"name":"Try it now - demo.pdf",
"recipients":[
{
"status":"finalized",
"first_name":"",
"last_name":"",
"order_id":1,
"last_modified_time":1505462568,
"recipient_user_id":2,
"recipient_id":5,
"created_time":1505462478,
"email":"[email protected]"
},
{
"status":"finalized",
"first_name":"",
"last_name":"",
"order_id":2,
"last_modified_time":1505462805,
"recipient_user_id":3,
"recipient_id":6,
"created_time":1505462478,
"email":"[email protected]"
}
],
"owner_email":"[email protected]",
"owner_last_name":"Barb",
"next":6,
"created_time":1505462478,
"last_modified_time":1505462568,
"has_markers":0,
"is_ordered":0,
"id":3,
"owner_user_id":1
},
"metadata":{
"event_type":"rs.signed",
"event_user_id":3,
"client_id":null,
"event_user":"[email protected]"
}
}
Signer declined to sign the document
This event is fired whenever a signer in a signature request declines to sign the document. The payload has details of who the signer is and the time of the event. Declining the document effectively voids the signature request for the other signers (if any).
Use this event to re-trigger a signature request or reaching out to your signers on why they declined to sign the document.
{
"data":{
"status":"recipient_declined",
"owner_first_name":"Jack",
"name":"Try it now - demo.pdf",
"recipients":[
{
"status":"declined",
"first_name":"",
"last_name":"",
"order_id":1,
"last_modified_time":1505462351,
"recipient_user_id":2,
"recipient_id":3,
"created_time":1505462028,
"email":"[email protected]"
},
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":2,
"last_modified_time":1505462028,
"recipient_user_id":3,
"recipient_id":4,
"created_time":1505462028,
"email":"[email protected]"
}
],
"owner_email":"[email protected]",
"owner_last_name":"Barb",
"next":null,
"decline_reason":"I do not agree with the terms",
"created_time":1505462028,
"last_modified_time":1505462351,
"has_markers":0,
"is_ordered":0,
"id":2,
"owner_user_id":1
},
"metadata":{
"event_type":"rs.declined",
"event_user_id":2,
"client_id":null,
"event_user":"[email protected]"
}
}
Request Signature voided
This event is fired when the user voids the signature request. This will effectively invalidate the signing links sent to all the signers.
This event will be useful in updating the statuses of your documents and dashboards.
{
"data":{
"status":"canceled",
"owner_first_name":"Jack",
"name":"Try it now - demo.pdf",
"recipients":[
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":1,
"last_modified_time":1505464109,
"recipient_user_id":2,
"recipient_id":7,
"created_time":1505464109,
"email":"[email protected]"
},
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":2,
"last_modified_time":1505464109,
"recipient_user_id":3,
"recipient_id":8,
"created_time":1505464109,
"email":"[email protected]"
}
],
"owner_email":"[email protected]",
"owner_last_name":"Barb",
"next":null,
"created_time":1505464109,
"last_modified_time":1505464247,
"has_markers":0,
"is_ordered":0,
"id":4,
"owner_user_id":1
},
"metadata":{
"event_type":"rs.voided",
"event_user_id":1,
"client_id":null,
"event_user":"[email protected]"
}
}
Signer was reminded to sign the document
This event is triggered whenever a signer in the signature request was reminded to sign the document. Note that this event is not fired for the automatic reminders the document signers receive from SignEasy everyday (upto 7 days).
{
"data":{
"status":"incomplete",
"owner_first_name":"Jack",
"name":"Try it now - demo.pdf",
"recipients":[
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":1,
"last_modified_time":1505464109,
"recipient_user_id":2,
"recipient_id":7,
"created_time":1505464109,
"email":"[email protected]"
},
{
"status":"not_viewed",
"first_name":"",
"last_name":"",
"order_id":2,
"last_modified_time":1505464109,
"recipient_user_id":3,
"recipient_id":8,
"created_time":1505464109,
"email":"[email protected]"
}
],
"owner_email":"[email protected]",
"owner_last_name":"Barb",
"next":7,
"created_time":1505464109,
"last_modified_time":1505464109,
"has_markers":0,
"is_ordered":0,
"id":4,
"owner_user_id":1
},
"metadata":{
"event_type":"rs.reminded",
"event_user_id":1,
"client_id":null,
"event_user":"[email protected]"
}
}
Request Signature Complete
This event is fired when all the signers in the signature request have signed the document and the signature request is now complete.
The payload contains details of signing time and the new signed_file_id of the completed document. Use this signed_file_id to fetch/download the document using the signed file download API.
Note that this signed file belongs to the sender's account.
{
"data":{
"owner_user_id":1,
"signed_file_id":"2",
"id":3
},
"metadata":{
"event_user":null,
"event_type":"rs.completed",
"client_id":null
}
}