Using the Interview Load Event Webhook to Get Initial Answer Data

Note: only users with the Site Administrator or Integration Administrator user role can manage webhooks.

An Interview Load Event webhook enables HotDocs Advance to populate interviews with answer data retrieved from your own web application. This event activates when the user opens an interview.


This webhook has the following prerequisites:

  • Creating a Webhook – you must have an existing webhook that:
    • Uses the Interview Load Event type
    • Has access to the work groups or templates in which you want the webhook to apply
  • Answer JSON that matches the variable names and structure of the Author template
  • An endpoint on your web application that accepts a GET request and returns a set of answer data


When you create an interview load event webhook, you specify an endpoint on your web application that accepts a GET request and returns answer data. This answer data must be in the HotDocs answer JSON format. 

The GET request to the endpoint is activated when a user opens an Advance interview. When the data is returned to the interview from your endpoint, Advance overlays the answer data into the interview, populating the answer fields for your user.

Your Existing Webhook

This example supposes that you have an existing webhook with the following properties:

  • Name – WebhookExample03
  • URLhttps://localhost/WebhookExampleApp/GetAnswerData
  • Event Type Interview Load Event (sends request to retrieve answer data when a user opens an interview)
  • Authentication method – exampleHMAC
  • Active StatusActive
  • Untrusted SSL certificatesNo
  • Work Groups - WorkGroupExample01
  • Templates - TemplateExample01

The URL for the webhook should point to the GET endpoint in your own web application.

Authentication method

The token specified in the webhook is passed in the request sent to your endpoint, in the Authorization header. HMAC authentication is the recommended authentication method to authenticate requests from Advance to your own application.

See also Authentication Types

Work Groups and Templates

The webhook only applies to the selected work groups and templates.

Data Sent from Advance to your Endpoint

When the Interview Load Event webhook is activated by a user, the webhook sends a GET request to your endpoint. The request contains a JSON string that includes the following data:

  • linkedVariable — typically null; may be populated with data passed from a template link's linkdata property
  • userContextData — the user context data for the template; this includes details about the user that activated the webhook

For example:

    "linkedVariable": { "ParameterValue": null },
    "userContextData": {
        "UserId": "8727d822-7b4a-5f6d-ab56-781f498af6cc", 
        "UserFirstName": "John",
        "UserLastName": "MacDiarmid",
        "UserEmailAddress": "",

You can use this information when constructing the data you will return to Advance. For example, if you need to look up information specific to the user making the request.

Data Sent from your Endpoint to Advance

The response sent back to Advance from your endpoint must be a JSON string that conforms to the HotDocs answer JSON format. For example, this answer set returns values for text, number, date, true/false, multi select, and repeat variables:

    {""n"":""textVar1"",""t"":""TX"",""v"":""Francis Smith""},
    {""n"":""dateVar1"",""t"":""DA"",""v"":""31 12 1999""},
    {""n"":""multiSelectVar1"",""t"":""TL"",""v"":{""v"":[""Option A"", ""Option B""]}},
    {""n"":""repeatVar1"",""t"":""TX"",""v"":[""Employed Full-Time"", ""Employed Part-Time"", ""Unemployed""]}


Getting Answer Data from an Existing Interview

You can use the HotDocs JavaScript API HD$.GetJSONAnswers function with an open HotDocs interview to quickly generate an example answer set. Running the command in the console of your browser's Developer Tools window retrieves the JSON answer data from the in-progress interview.

Validating Your Answer Data

You should validate your answer data before sending it to Advance. See Validating HotDocs Answer Sets for more information.

JSON Response Data Size

The size of JSON response data is limited to 200Kb by default. If your response data is often larger than this, you can change the default allowable size by adding the ExternalAnswersMaxBytes setting to your HdaInstallerSettings.json file. In between the "SiteSettings": braces add the following setting, replace 200 with the number of bytes you require:

"ApiSiteSettings.AppSettings.ExternalAnswersMaxBytes": 200,

This setting can be added before the installation of Advance. If you have already installed Advance, you can add this setting to the installer settings file and run the Hdainstaller.exe setting gu installer command. This uses the updated installer settings file to update the configuration of your installed version of Advance.

If other settings are listed below, ensure the comma at the end of the ExternalAnswersMaxBytes setting is included. If you add the setting below all other settings, then a comma is not required.

Please note that large JSON response data files can affect interview performance.

This setting affects custom interview and load interview event webhooks.