Skip to main content

Webhooks on Legalesign

What are webhooks

Webhooks are your URLs where we will send status updates. Use webhooks and avoid polling.

Types of webhook

There are two types of webhook. A realtime notification and a general update.

The general update webhook is sent every 6 minutes. It's a JSON object that tells you everything that happened in your account in the last 6 minutes.

The realtime notifications are POST requests that are delivered very soon after an event. There are several triggers for realtime notifications: after a signing, after a doc is sent (created), and if a doc is rejected.

info

The typical use case is to set an 'after signing' webhook, and use that to trigger a download of your signed PDF. This webhook is sent once the final PDF is created (not precisely on the signing moment), so you can be sure you'll be able to download your signed PDF.

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

Below, in seeking to understand how to parse webhook data, we'll be using these two temporary ngrok addresses to examine the content back from the general update webhook and 'upon signing' webhook.

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, 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 go to, API webhooks

Parsing webhook data, what's in a webhook?

Ngrok is a great tool to example the content of a webhook in local. Run a few tests and you can use ngrok to examine the contents, and then use that as test data in your own coding.

info

Ensure your webhook code returns a success response (or set a variety of failure responses codes) to help you debug webhooks in the API dashboard.

Once ngrok is running go to http://127.0.0.1:4040/inspect/http to see what's come in.

The format of realtime webhooks

Here's what ngrok has to say about a realtime 'upon signing' webhook:

signed webhook in ngrok

As you can see, this request comes in like a normal POST data request. It's content type is application/x-www-form-urlencoded. You can treat it like a normal POST request.

The data about the signed document is quite limited, if you need more data use the resource_uri to query for all the data about the document.

tip

The data contains the document 'tag'. You can set a tag when you create/send the document. By using tag and the signed webhook you might not have to save Legalesign IDs.

All the realtime notifications - sent, signed and rejected follow this POST format.

warning

Don't forget to turn off CSRF protection for the view that receives these POST requests.

The format of a general update / 6 minute webhook

In the meanwhile, the 6 minute call we had set to the same ngrok url has arrived. It 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's 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.

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
30Signed
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
40Signed
50Downloaded
60Rejected

Debug webhooks in the API dashboard

...details coming soon

(go 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