Webhooks guide

Learn about API webhooks, which may be used by external apps and integration to trigger external workflows based on LawVu events.

Introduction

The LawVu Webhooks API is provided to allow external apps and integrations to receive notifications about events happening within LawVu, so that you can trigger external workflows in near real-time.

For example, instead of having periodically “poll” the LawVu API to find out if changes have been made to a matter, a file has been uploaded, or contract has been executed, your integration can simply register to receive webhook notifications at an HTTP endpoint of your choosing and act on those notifications as they are received.

To leverage LawVu webhooks, you must:

be provided with LawVu API access and a developer sandbox with which you can build and test your integration prior to gaining production credentials.
provide a secure (HTTPS), publicly accessible endpoint which will be used by your integration to receive, process and respond to webhook notifications.

Webhooks are created under the security context of an individual user, not an organisation.

Therefore we recommend the use of a nominated user account which has the appropriate access level within LawVu.

Subscriptions

To receive webhook notifications when events occur in LawVu, a subscription must be registered. Subscriptions contain details on which events (topics) the notifications should be sent for and where the notifications should be sent to (subscription URL).

About subscriptions

The LawVu Account / Create a subscription endpoint provides a full breakdown of the different properties for a subscription. Below is additional information to help you understand some aspects and requirements:

A subscription URL must be https and a maximum length of 2048 characters. It can contain query string information, which can be used for filtering or other identification within your integration.
An optional client state value can also be provided as part of the subscription, this is included with each webhook notification sent by the LawVu API to your endpoint. See Client State for more detail.
It is not possible to update a subscription. If you wish to make changes, please delete the existing subscription and create a new subscription.
Subscriptions do not expire, however they can be disabled – see Failed notifications below
All interactions with the subscription endpoints require the same authentication as other endpoints in the LawVu API, please see the Authentication guide for more information.

Example: Create a subscription

The below example demonstrates creating a subscription for events when a matter is created or updated. When these events occur, a webhook notification will be sent to https://myapplication.com/webhooks?id=10

    POST /account-apis/v1/webhooks/subscriptions

    {
      "topics": [
        "matter.created",
        "matter.updated"
      ],
      "subscriptionUrl": "https://myapplication.com/webhooks?id=10",
      "clientState": "510dbf3c-fa88-4c06-89dc-c7be29c6f55a"
    }

Example: Get all subscriptions

The below example demonstrates how to retrieve a list of subscriptions created by the authenticated user (not organisation).

The response will include an array of all subscriptions with the associated details (example returns two subscriptions):

    GET /account-apis/v1/webhooks/subscriptions

    [
        {
            "id": 619,
            "topics": [
                "matter.created",
                "matter.updated"
            ],
            "subscriptionUrl": "https://myapplication.com/webhooks?id=10",
            "clientState": "510dbf3c-fa88-4c06-89dc-c7be29c6f55a",
            "status": "active",
            "createdDateUtc": "2023-01-08T21:36:48.71",
            "createdBy": "user@myorganization.com",
            "modifiedDateUtc": "2023-01-08T21:36:48.71",
            "modifiedBy": "user@myorganization.com"
        },
        {
            "id": 712,
            "topics": [
                "contract.created",
                "contract.status.updated",
                "contract.document.updated"
            ],
            "subscriptionUrl": "https://myapplication.com/webhooks?id=12",
            "clientState": "secretstring",
            "status": "active",
            "createdDateUtc": "2023-01-16T21:51:49.85",
            "createdBy": "user@myorganization.com",
            "modifiedDateUtc": "2023-01-16T21:51:49.85",
            "modifiedBy": "user@myorganization.com"
        }
    ]

Example: Delete a subscription

The below example demonstrates deleting a subscription with ID 619:

DELETE /account-apis/v1/webhooks/subscriptions/619

A successful response code will be 204.

To find the ID of your subscription, use the Get all subscriptions endpoint.

Topics

The LawVu events available for subscriptions are organised into topics. Notifications are triggered whenever the underlying event occurs, regardless of source (LawVu app, Outlook add-in, LawVu API, signing integration, etc.).

Topics have slightly different behaviour, below is a full list of available topics and expected behaviours.

Topic	Description	Parent Resource	Deduplication	Delay window
matter.created	When a matter is created	N/A	No	N/A
matter.updated	When a matter is updated – any change to one of the following: Name Team Assigned Matter Type Custom Fields State Owner Manager (including intake) Restricted Urgent External ID Parent Matter Tags Status Message	N/A	Yes	2 minutes
matter.status.updated	When the state of a matter is updated	N/A	No	N/A
matter.file.created	When a file is added to a matter	Included	No	N/A
matter.file.updated	When a file is updated in a matter	Included	No	N/A
matter.statusmessage.created	When a new status message is posted to a matter	Included	No	N/A
matter.tag.created	When a tag is added to a matter	Included	No	N/A
contract.created	When a contract is created	N/A	No	N/A
contract.updated	When a contract is updated – any change to one of the following: Name Team Assigned Contract Type Custom Fields Stage Owner Restricted Contract Value Expiry Date Executed Date External ID Parent Matter Status Message	N/A	Yes	2 minutes
contract.status.updated	When the stage of a contract is updated (e.g. approval to signing)	Included	No	N/A
contract.file.created	When a file is added to a contract (note: only applies to the files which appear in the Files tab in LawVu)	Included	No	N/A
contract.file.updated	When a file is updated in a contract (note: only applies to the files which appear in the Files tab of LawVu)	Included	No	N/A
contract.document.updated	When the contract document is updated	Included	No	N/A
contract.statusmessage.created	When a new status message is posted to a contract	Included	No	N/A
contract.keydate.created	When a new key date is created on a contract	Included	No	N/A
contract.keydate.updated	When a key date is updated on a contract	Included	No	N/A

Parent Resource

The notification will contain the parent resource relationship (see Notifications below).

Deduplication

The notifications for this topic will be deduplicated within the delay window, any notifications for the same resource (e.g. matter) and topic (e.g. matter.updated) will be trimmed to avoid duplicate notifications.

Example, if a user is updating a number of fields on a matter within a short timeframe, only one notification is sent rather than a notification per field changed.

Note: Deduplication occurs based on the topic rather than subscription, it is still possible to receive a notification for the same event twice in some circumstances. For example, a subscription that is subscribed to the topics matter.updated & matter.status.updated will receive two notifications when the matter state changes (one for matter.updated and one for matter.status.updated). The payload of the notification will indicate which topic the notification belongs to, see Notifications below.

Delay window

The timeframe for which deduplication occurs, with a single notification being sent at the end of the delay window.

Notifications

When an event that relates to a subscribed topic occurs in LawVu, a notification is sent to the relevant subscription URL via an HTTP POST request. The notification is generally sent within 10 seconds of the event occurring, except where a delay window is used for that topic (see Topics).

Examples:


    // Topic: matter.created  (a new matter has been created):
    {
       "Timestamp": "2023-01-21T21:29:55.0798512Z",
       "ResourceId": 96660,
       "EventType": "matter.created",
       "ClientState": "510dbf3c-fa88-4c06-89dc-c7be29c6f55a"
    }
    
    // Topic: matter.file.created  (a new file has been uploaded to a matter):
    {
       "Timestamp": "2023-01-21T21:38:06.7758226Z",
       "ResourceId": 295061,
       "EventType": "matter.file.created",
       "ClientState": "secretstring",
       "ParentResource": {
           "ResourceType": "matter",
           "ResourceId": 96660,
       }
    }

Notification body details

The notification body will always be a single object, containing the following fields:

Timestamp: The date and time (UTC) the event occurred
ResourceId: The id of the resource related to the notification e.g. matter. This id can be used to query the relevant resource from the LawVu API
EventType: The topic which the notification was generated for (see Topics table)
ClientState: The value supplied when the subscription was created (see Client state below)

No further detail on the event is provided. The ResourceId can be used to query the appropriate LawVu API endpoint to determine more information.

Parent Resource in notifications

Depending on the topic, a parent resource object may also be included in the notification body (see Topics table for topics which include parent resources).

This object details the related parent resource (e.g. matter) for a notification which relates to a sub-resource (e.g. file). The ParentResource object is made up of the following fields:

ResourceId: The id of the parent resource related to the notification e.g. matter. This id can be used to query the relevant resource from the LawVu API
ResourceType: The type of parent resource e.g. matter or contract

Processing Notifications

When your endpoint receives webhook notifications from LawVu, it must acknowledge it by responding with a 2xx response code within 5 seconds. If your integration does not respond in this way, the failed notification process will begin (see below). It is recommended that your integration responds as early as possible in processing to ensure duplicate notifications aren’t received due to redelivery of unacknowledged notifications.

Failed notifications

Redelivery

If a message isn’t acknowledged following the expected behaviour, the LawVu API will attempt to deliver it again in the following pattern:

On first failure: resend notification after a one minute delay
On second failure: resend notification after a two minute delay
On third failure: resend notification after a five minute delay
On fourth failure: do not attempt to redeliver, abandon notification

Subscription Disabled

If 10 notifications for a particular subscription within a 24 hour period are abandoned (redelivery is unsuccessful), that subscription will be disabled and no longer receive notifications of new events. To enable the subscription again, it must be recreated.

Security

The LawVu API Webhooks system follows common patterns for webhook security. Review the following considerations to ensure LawVu API Webhooks are suitable for your purpose.

Subscription URL / Notification endpoint validation

Provided the subscription URL meets the criteria outlined above, no further validation is performed on the supplied endpoint. You need to ensure it is appropriately available, responsive and secured to ensure only your integration has access to notifications being sent to it.

LawVu API Webhooks does not support any subscription URLs that require authentication or are not publicly accessible.

Notification IP Address

Notifications will be sent by a service hosted in the Microsoft Azure region corresponding to your LawVu account. If you require whitelisting these addresses, please contact LawVu support.

Data Access

Notifications respect the access level of the user which created the subscription. Therefore, the user must have access to the resource the event is being carried out on (e.g. the matter which state has changed) otherwise no notification be generated.

It is recommended that permissions for webhook users are carefully planned for the following considerations:

Restricted items being incorrectly included/excluded
Account expiry/removal

Client state

The ClientState property of a subscription is a simple mechanism that can be used to help validate the notification sent comes from the LawVu API and not a third party. It should remain secret outside of the LawVu API & your integration and be validated for each incoming notification.