Webhooks on Legalesign
What are webhooks
Webhooks are your URLs where Legalesign will send status updates. Use webhooks and avoid polling.
Add or remove webhooks in the app where you find your API key.
Types of webhook
There are three types of webhook.
- All realtime events
- All events every 6 minutes (deprecated)
- Upon [event] (deprecated)
Use the webhook called 'All realtime events'.
This is realtime POST containing JSON. This webhook will alert you to everything you need, with more data than the other webhooks. You can also filter data by group and/or events.
If this webhook does not fire for an event you need, or you need more data, contact us.
The most common use-case is to listen for the finalPdfCreated event, in order to trigger a download of the final PDF. Filter requests for 'document' and 'finalPdfCreated'. When you receive the event, extract the document UUID from the data packet (data['uuid']) and issue a GET to download API endpoint (/api/v1/pdf/+data['uuid']+/).
How to add or remove a webhook
You can use the web app or the API to manage webhooks.
Add or remove a webhook using the web app
Go to settings and you'll see the webhooks panel. The form has simple controls to add or remove webhooks
Your API key is based on your account and not an individual group or organisation. This gives your API key more flexibility, but your webhooks will get information from all accounts where you are an admin, both dev and prod. To differentiate webhooks by group either use the filter, or (the old method) create new admin user only a member within the target group(s), get them an API key, and use that account for your webhook.
Add or remove a webhook using the API
Use simple GET and POST requests over the REST API to list, create or delete webhooks.
For more information see the documentation: API webhooks
What's in a webhook?
The quickest way to do this is add a webhook, send/sign/reject some test documents in the web app, and inspect the contents in the Legalesign API Dashboard.
If you need a temporary webhook URL for testing (that you can inspect too) then check out ngrok.
Once you have ngrok, fire it up in terminal with ./ngrok http 80 and it will give you an https address. Enter that as your webhook.
Now open http://127.0.0.1:4040. That's it, you'll start seeing all the webhooks and their data. Start sending and signing test docs.
Ensure your receiving webhook code returns a success response (or set a variety of failure responses codes) to help you debug webhooks in the API dashboard.
The format of realtime webhook
This is what ngrok shows for a realtime 'all events' webhook:
The request comes in as a POST request containing JSON.
See the top level keys 'object' and 'event'. In the image above they contain 'document' and 'created' respectively. These two keys uniquely identify all the events. All possible combinations of object and event are listed below.
The format of 'data' depends on 'object'.
In the image above the object is a 'document'. All events for 'document' will have the same data structure. You'll notice the data for 'recipient' object is slightly different (see image below). But the shape of that recipient data object will be consistent for all other recipient events.
Note the document attribute 'tag'. You can set a tag when you create/send the document. By using tag you might not have to save Legalesign IDs. (Also tag1 and tag2 if more tags required.)
Table of combinations for 'object' and 'event' are:
| object | event |
|---|---|
| document | created |
| document | rejected |
| document | finalPdfCreated |
| recipient | completed |
| recipient | rejected |
(More coming soon.)
Don't forget to turn off CSRF protection for your view receiving these POST requests.
Here is an example of what a 'recipient' object looks like, in contrast to the 'document' example above:
The format of a general update / 6 minute webhook
The 6 minute call looks like this:
As you can see it is also a POST request. But this time all the information is stored in the 'data' POST attribute as a JSON object.
Here's that JSON object in detail:
[
{
"value": "5",
"timestamp": "2022-07-11T07:28:25+00:00",
"resource_uri": "/api/v1/signer/656926a1-a9e9-434b-91cc-9f9769254e99/",
"name": "status"
},
{
"value": "10",
"timestamp": "2022-07-11T07:28:26+00:00",
"resource_uri": "/api/v1/signer/656926a1-a9e9-434b-91cc-9f9769254e99/",
"name": "status"
},
{
"value": "20",
"timestamp": "2022-07-11T07:28:55+00:00",
"resource_uri": "/api/v1/signer/656926a1-a9e9-434b-91cc-9f9769254e99/",
"name": "status"
},
{
"value": "20",
"timestamp": "2022-07-11T07:29:06+00:00",
"resource_uri": "/api/v1/document/6619179c-95da-4d5c-b7be-7bac0bac4088/",
"name": "status"
},
{
"value": "30",
"timestamp": "2022-07-11T07:29:06+00:00",
"resource_uri": "/api/v1/signer/656926a1-a9e9-434b-91cc-9f9769254e99/",
"name": "status"
},
{
"value": "40",
"timestamp": "2022-07-11T07:29:06+00:00",
"resource_uri": "/api/v1/signer/656926a1-a9e9-434b-91cc-9f9769254e99/",
"name": "status"
},
{
"value": "30",
"timestamp": "2022-07-11T07:29:06+00:00",
"resource_uri": "/api/v1/document/6619179c-95da-4d5c-b7be-7bac0bac4088/",
"name": "status"
},
{
"value": "100",
"timestamp": "2022-07-11T07:29:09+00:00",
"resource_uri": "/api/v1/document/6619179c-95da-4d5c-b7be-7bac0bac4088/",
"name": "status"
}
]
What is going on here? The general update webhook is now giving you all the detail about what happened in the signing of a document, and when. It includes event updates for both a signer and a document.
You will have noticed that we use the words 'recipient' and 'signer'. These are interchangeable. The use of recipient reflects the more complex roles that are now available in Legalesign and will be the new name for 'signer' as we develop.
The story of this webhook data is the signer object was created (signer 5), sent (signer 10), the signer completed their field (signer 30), and signed (signer 40), the document noted its fields were complete (document 20) was then marked as signed (document 30), and then ready for download (document 100).
'100' is a special event code to confirm a document is ready to download.
Document status
| Status | Explanation |
|---|---|
| 10 | Sent |
| 20 | Fields completed |
| 30 | Complete |
| 40 | Removed (before signing) |
| 50 | Rejected |
Signer status
| Status | Explanation |
|---|---|
| 4 | Unsent |
| 5 | Scheduled to send |
| 10 | Sent |
| 15 | Email opened |
| 20 | Visited |
| 30 | Fields completed |
| 35 | Fields done except signature fields |
| 39 | Witness to sign |
| 40 | Completed |
| 50 | Downloaded |
| 60 | Rejected |
Debug webhooks in the API dashboard
All webhooks are logged and you can examine their content and the http status code in your API dashboard. To learn more check out the Dashboard tutorial
Go to direct to API dashboard.
Contact us
That should covers everything you need to know about webhooks.
If you have any more questions please get in touch support@legalesign.com