Skip to main content

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.

info

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

webhooks panel

danger

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.

info

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:

document data in ngrok

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.

tip

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:

objectevent
documentcreated
documentrejected
documentfinalPdfCreated
recipientcompleted
recipientrejected

(More coming soon.)

danger

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:

recipient data in ngrok

The format of a general update / 6 minute webhook

The 6 minute call looks like this:

6 minute webhook

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.

danger

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

StatusExplanation
10Sent
20Fields completed
30Complete
40Removed (before signing)
50Rejected

Signer status

StatusExplanation
4Unsent
5Scheduled to send
10Sent
15Email opened
20Visited
30Fields completed
35Fields done except signature fields
39Witness to sign
40Completed
50Downloaded
60Rejected

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