Push API (Webhooks)

Push API – Webhooks

Legito’s Push API enables your application’s web server (a webhook listener) to receive instantaneous automated messages contain Document Record details (including Documents and Files) that are triggered by any Document Record Event.  A Triggering Document Record Event may be any of the Event types captured by Legito’s Document Timeline (Audit Trail).

As a webhook service, our Push API actively sends (pushes) up-to-date information to your subscribed services when specified events in your Workspace occur, versus your having to “call” and retrieve information. It is this active “pushing” of information that differentiates it from REST API.

Webhooks are “user-defined HTTP callbacks” that are sent to a unique URL address (essentially the application’s phone number). They are much like SMS notifications. Webhooks are almost always faster than polling and require less work on your end.

1) Push API Settings

The first step in using Legito’s Push API is the configuration of your webhook subscription (Push Connections in your Legito Workspace.

Push Connections define what data will be sent from Legito and when, as well as to which URL address.

Push Connections can be created:

a) In a user interface by Workspace Admins, or

b) using Legito’s REST API.

To create, modify, activate, deactivate, or delete Push Connections in the Legito user interface, go to My account => Settings => Push API.

Click the “Create” button in the upper right corner of your screen to set a new Push Connection. To maintain security, each newly created Push Connection must be enabled before use. Click the corresponding “Disabled” button from the list of Push Connections to enable it.

See our REST API documentation to learn more about creating Push Connections this way including the following methods:

• get push-connection
• post push-connection

All Push Connection created via our REST API will also be displayed in the user interface.

2) Push Connection Details

Name

Name of the Push Connection.

URL address

URL address of your application’s web server (webhook listener).

A Webhook listener must include an HTTPS URL to which Legito can POST. This URL address must be available on the public internet and not protected by a firewall.

Version

Aligned with REST API.

Custom Headers

It is possible to add multiple headers, where each header consists of a Header Name and a corresponding Value.

A Value may contain the variables described below. If a variable is used, it will be displayed in curly brackets, for example {LEGITO.currentUser.name}.

Custom headers allow you to implement more sophisticated logic and security on the listener’s side.

The following new variables (objects) are available for inclusion in your Custom Headers:

• documentBuilder.event
• LEGITO.currentUser
  • Action-triggering User Name: LEGITO.currentUser.name
  • Action-triggering User Email: LEGITO.currentUser.email
  • Action-triggering User ID: LEGITO.currentUser.id
  • Action-triggering User Position: LEGITO.currentUser.position
  • Action-triggering User Custom Data: LEGITO.currentUser.customData

Action-triggering User is a user that performed the action in the Legito’s user interface, for example a user that clicked to the Save button.

• LEGITO.defaultApiUser objects
  • Default API User NameLEGITO.defaultApiUser.name
  • Default API User Email LEGITO.defaultApiUser.email
  • Default API User ID LEGITO.defaultApiUser.id
  • Default API User Position LEGITO.defaultApiUser.position
    Default API User Custom Data LEGITO.defaultApiUser.customData

Default API User is the user that is defined in the API Keys section of the Workspace Settings.

Triggering Events

Push Connections can be triggered by one or more Event types. It is possible to choose from any Event types captured in Legito’s Document Timeline.

Each Push Connection should have at least one triggering Event type. If you set more than one triggering Event type, each occurrence of the respective Event will trigger the Push Connection individually.

Template Suites

Each Push Connection can be limited to Document Records of Documents created from a selected Template Suite, or multiple Template Suites (applicable to the Document Records created from automated Templates).

Document Record Types

Each Push Connection can be limited to a selected Document Records Type, or multiple Document Record Types. (applicable to manually created Document Records).

Attached Files

Legito Documents exported to any supported formats (although typically Word or PDF), and/or uploaded Files, may be attached to each pushed message.

All documents (files) attached in this manner are sent encoded in Base64.

Formats of generated Legito Documents

Similar to the manual download of Legito Documents, it is possible to choose the format in which documents will be sent, including the most popular ones – Word and PDF.

If documents are attached are sent through Push connections, users familiar with utilizing Advanced Layout Designs for exporting Legito Documents to Word or PDF, will find that documents attached to pushed messages will contain documents generated according to the respective Template’s default Advanced Layout Design.

3) Pushed Information

Pushed messages are in JSON (JavaScript Object Notation) format.

Document Records Owner, Workflow Stage and other Document Record Properties data (excluding Chat, Approvals, and associated Document Records) are sent as meta data within each pushed message.

Based on the Push Connection configuration, the settings, names, formats, Document Record ID and Code, Template Suite ID, file size, and content (encoded in Base64) of Files, and generated Documents contained in a Document Record may also be included in the message.

The general structure of each message pushed to a webhook listener is as follows:

The precise structure of each Pushed Connection is available in Push API Logs.

4) Logs

Push API Logs assist with the efficient integration of your webhook listener to each Push Connection.

To view Push API Logs, go to My account => Settings => Push API and click the “Logs” button in the upper right corner of your screen.

Each Push API Log contains the following info:

• Push Connection Name
• Timestamp
• Request Body

This section contains the precise structure of the pushed message that will help you configure your webhook listener correctly.

Due to our efforts to reduce the length of the Push API Logs, file content (data) is excluded from logs and replaced by the following text: “Base64 encoded file data is not present in logs.”

Example of the files section in Push API Logs:

• Response Code

Response Code section contains a standard list of HTTP status codes. Code “200” is your preferred code. Code 0 indicates that the URL of your webhook listener is not available and the connection was not established at all.

• Response Header & Response Body

These sections are purely informative. Responses to pushed messages from your webhook listener cannot change anything in your Workspace. Modifications, or any type of standard use of your Documents or Document Records, i.e., creating / modifying Properties, saving or downloading / uploading, or applying users, should be done using Legito’s REST API.

• Response Error

Response Error section contains information that will help you find errors in the integration with the webhook listener.

If the Response Code is 200 (everything is OK), the Response Error section will be left blank.

Push API Logs are stored for 30 days. If you need more time, please contact us at automation@legito.com.