Skip to main content

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

info

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.

webhooks panel

danger

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.

info

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):

document data in ngrok

The request comes in as a POST request containing JSON.

The contents of data may expand to include more fields over time.

tip

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':

objectevent
documentcreated
documentrejected
documentfinalPdfCreated
recipientcompleted
recipientrejected
recipientemailOpened
recipientvisiting
recipientbounced

Most events only occur once. The exceptions are visiting and bounced, they may occur many times.

danger

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':

recipient data in ngrok

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