Webhooks Overview

A webhook is a configurable function that sends a notification to a specified endpoint when a specific event occurs in Advance. This enables you to automate processes and integrate Advance with other applications.

For example, you can configure a webhook to send a notification to an endpoint in your own web application when a user completes a new work item version.

Overview

Webhooks in Advance allow you to receive notifications and retrieve data from your own web application when specific events occur. For example, you can configure a webhook to activate when a user begins a new interview, which is useful for prepopulating an interview with an answer set stored in your own web application. In this example scenario, you may have an application that must be notified when a user begins a new interview, so Advance can retrieve the user's details and prepopulate the interview with their data.

To use Advance webhooks, your application must have an endpoint to receive JSON data sent by the webhook. For example, the data for a Load Interview event includes the user's account details, such as their ID, name, and email address. Your application must also accept authentication tokens to verify the event data sent by Advance.

Common Tasks

Among others, webhooks enable you to perform the following common tasks:

Workflow

You typically create a webhook when you have an existing application that must be notified when a particular event occurs in Advance.

This functionality works with work items, and is therefore not available with quick documents.

Requirements for your application

When creating a web hook, you must provide the following items of information:

  • URL – the URL of an endpoint in your application to which Advance sends the event data

You must ensure that you can provide this item of information before you can create the webhook.

Event Types

The following event types are available when you create a webhook:

  • New work item version complete
  • Custom interview event
  • Interview load event
  • Post-assembly processing event

New Work Item Version Complete

The NewWorkItemVersionComplete event occurs when a user completes an assembly for an existing work item. This event typically indicates that the work item has new documents available. This is useful if your application needs to retrieve new documents from Advance and store them in another system.

Custom Interview Event

The CustomInterviewEvent event occurs when a user interacts with a interview event dialog element component in the interview. This is useful if, for example, your users need to retrieve answer data from an external source during the interview. One interview could have a series of webhooks providing data lookups for different variables.

Load Interview Event

The InterviewLoadEvent event occurs when a user opens an interview. This is useful if, for example, your users need the interview to be prepopulated with answer data from an external source. The data you return is overlaid into the answer set before the user starts adding their own answers.

Post-assembly processing Event

The PostProcessingEvent event occurs when a user completes an assembly for an existing work item. This is useful if you want to modify an assembled document before the document is made available to the user. This webhook is set up for your Advance site, you then select which templates you wish it to apply to. When a user assembles a document based on a selected template, data is sent to your endpoint. You can then process the documents, by adding a QR code or a digital signature for example, and return them to Advance.

Using multiple webhooks

You can use the webhook event types in combination. For example, you may want to overlay some initial data using the InterviewLoadEvent and then look up data during the same interview using the CustomInterviewEvent.

There are no limits to the numbers of CustomInterviewEvent webhooks you can set up for an interview. Similarly, you can overlay a series of answer data using the InterviewLoadEvent multiple times. However in this case you should take care to ensure you overlay the data in the intended order.

The post-assembly processing event webhook applies to your Advance site rather than individual interviews or work items. You can only set up one webhook but you can select which of your templates should trigger the webhook event. When a user assembles a document based on selected templates, the webhook activates and sends data to your endpoint. From there, you can process the data through one or multiple operations should you wish, according to your own needs and design.

The NewWorkItemVersionComplete event is triggered whenever a new version of a work item is generated. You configure this webhook by work group and template. One work item could have a series of versions, Advance notifies your application each time it completes a new version.

Authentication Types

Advance provides two methods of authentication for webhooks, HMAC authentication and token authentication. You will use one of these methods to authenticate data sent from Advance to your web application.

HMAC Authentication

HMAC authentication is the recommended authentication method for webhooks. It ensures the integrity of the data sent from a webhook by encoding the data as a JWT token.

When you first create a webhook, Advance provides an HMAC secret to you. When your application receives data from a webhook, it must use the JWT library and the HMAC secret to authenticate the data received. This enables your own web application to check the authenticity and integrity of the data being sent from Advance.

Updating existing webhooks to use HMAC authentication

If you want to update an existing webhook to use HMAC authentication, edit the webhook and change the authentication method to HMAC authentication. Advance will provide a new HMAC secret for the webhook.

Regenerating an HMAC secret

If you want to change the HMAC secret of an existing webhook which you have configured to use HMAC authentication, edit the webhook and click Regenerate HMAC Secret. Advance will provide a new HMAC secret for the webhook.

Code Example

See the Action Links Endpoint Code Example for a code example of using the JWT library and the HMAC secret to authenticate data.

Token Authentication

Note: this is a legacy authentication option. It is recommended you use HMAC authentication for new webhooks and upgrade existing webhooks where possible.

Token authentication uses an access token that you supply when creating the webhook. The token specified in the webhook is passed in the request Advance sends to your endpoint, in the Authorization header. You should always authenticate requests from Advance in your own application using this token.

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.

Receiving Data from a Webhook Code Examples

See the following topics for information about receiving data from webhooks in your own web application: