Webhooks on Legalesign
What are webhooks
Webhooks are your URLs where Legalesign will send realtime status updates.
Why you need webhooks
Use webhooks to create your own live dashboard and sync your data. Use webhooks, not polling.
Types of webhook
- All realtime events
- All events every 6 minutes (legacy)
- Upon [event] (legacy)
Use the webhook called 'All realtime events'. For legacy webhooks see: legacy webhooks
TL;DR the most common use-case is to listen for document signing to trigger a final PDF download. Add your webhook url in the app settings and filter for 'document' and 'finalPdfCreated'. When you received the event get the document UUID from the data packet (data['uuid']). Then issue a GET to the download API endpoint (/api/v1/pdf/+data['uuid']+/).
How to add or remove a webhook
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. In the image below an ngrok endpoint is receiving all events.
Your webhooks receive events from all accounts where you are an admin, both dev and prod. To differentiate webhooks by group use the webhook group filter.
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 API documentation: REST API webhooks
What's in a webhook?
The quickest way to inspect your data is to add a webhook, send/sign/reject some test documents in the web app, and then view the webhooks log in the Legalesign API Dashboard.
If you need a temporary webhook URL for testing (that you can inspect too) then check out ngrok.
Quick how-to on ngrok: once you download ngrok, fire it up in the 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.
In your own code, ensure your receiving webhook code returns a 2XX success response. If you have several possible exceptions in your code it may be helpful to you to return different 5XX status code in each case. By inspecting the webhook logs in the API dashboard you will be able to discover which exception was triggered. In ngrok you may see 2 requests for each event, this is because ngrok is returning a 5XX error which forces a second attempt to send you the data.
The format of realtime webhook
Below is the content of a webhook for a "document" object. The important categories are "event" and "object". The shape of the "data" section will depend on the "object". A table of all possible objects and events is further down. This image illustrates a document object (for a 'created' event):
The request comes in as a POST request containing JSON.
The contents of data may expand to include more fields over time.
Note the document tag attributes. You can set a tag when you create a document. By using tags you may not have to save Legalesign IDs. You can also use tag to save a secret in order to verify the inbound request (thank you Themis for that suggestion).
Table of possible combinations for 'object' and 'event':
| object | event |
|---|---|
| document | created |
| document | rejected |
| document | finalPdfCreated |
| recipient | completed |
| recipient | rejected |
| recipient | emailOpened |
| recipient | visiting |
| recipient | bounced |
Most events only occur once. The exceptions are visiting and bounced, they may occur many times.
Don't forget to turn off CSRF protection for your view receiving these POST requests.
Here is an example of a 'recipient' object, with event 'bounced':
Notice emailBounce and emailBounceMessage in 'data'. 'emailBounceMessage' will indicate the type of bounce as follows:
- Hard bounce: "Message hard bounced"
- Soft bounce: "Email soft bounced (either out of office or a timeout)"
- Delayed: "Message delayed (check email domain exists)"
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.
Status codes
Click these links to see the reference table for document status and recipient status.
Contact us
That should covers everything you need to know about webhooks. If you need more webhooks for different events, or more data in them, contact us and get your request in the development pipeline.
If you have any more questions please get in touch support@legalesign.com