Getting Answer Data from an External Data Source

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

The Custom Interview Event webhook enables you to populate HotDocs interviews with answer data retrieved from your own web application.

Prerequisites

This webhook has the following prerequisites:

  • An Author template containing an Interview Event dialog element; this is the component which triggers the webhook in interview.
  • You must know the Event Name used in the interview event dialog element; this is used when setting the Interview Event Name for the webhook.
  • Creating a Webhook – you must have an existing webhook that:
    • Uses the Custom Interview Event type
    • The Interview Event Name property matches the Event Name in the interview event dialog element
  • 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

Overview

When you create a custom interview 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 and clicks an interview event dialog element that has the same Event Name property as your webhook. 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 – WebhookExample02
  • URLhttp://localhost/WebhookExampleApp/GetAnswerData
  • Tokenexampletoken
  • Event Type Custom Interview Event (sends request to retrieve answer data when)
  • Interview Event NameGetAnswerData
  • Active StatusActive
  • Untrusted SSL certificatesNo

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

The Interview Event Name must match the Event Name property for the interview event dialog in your template.

Token

The token specified in the webhook is passed in the request sent to your endpoint, in the Authorization header. You should always use this token to authenticate requests from Advance to your own application.

Data Sent from Advance to your Endpoint

When the Custom Interview 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 — the name of the linked variable in the interview event dialog element that activated the webhook
  • userContextData — the user context data for the template; this includes details about the user that activated the webhook

For example:

{
    "linkedVariable": { "ParameterValue": "EmployeeNameTextVariable" },
    "userContextData": {
        "UserId": "8727d822-7b4a-5f6d-ab56-781f498af6cc", 
        "UserFirstName": "John",
        "UserLastName": "MacDiarmid",
        "UserEmailAddress": "jm@example.com",
        ...
}

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, and multi select variables:

"[
    {""n"":""textVar1"",""t"":""TX"",""v"":""Francis Smith""},
    {""n"":""numberVar1"",""t"":""NU"",""v"":123},
    {""n"":""dateVar1"",""t"":""DA"",""v"":""31 12 1999""},
    {""n"":""trueFalseVar1"",""t"":""TF"",""v"":true},
    {""n"":""multiSelectVar1"",""t"":""TL"",""v"":{""v"":[""Option A"",""Option B""]}}
]"

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.