Concept Topic

Webhooks Overview

A webhook is a configurable function that sends a notification to an endpoint when a particular event occurs in Advance.

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 enable Advance to notify your own web application and retrieve your data when specific events occur in Advance. For example, you can configure a webhook to activate when a user begins a new interview. This is useful if you want to prepopulate 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 work with Advance webhooks, your application must have an endpoint to which Advance can send data about the event. When the event occurs, the webhook sends JSON data to your endpoint. For example, the data for a Load Interview event includes data based on the user's account details, such as the user's ID, name, and email address.

Your application must also accept authentication tokens, to authenticate the event data sent to your application's endpoint from Advance.

Common Tasks

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

• View a Webhook
• Create a Webhook
• Editing a Webhook
• Activating or Deactivating a Webhook
• Deleting a Webhook

Workflow

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

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.

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.

Post-assembly processing Event

The PostProcessingEvent event occurs when a user completes an assembly for an existing work item. This is useful if, for example, you want to modify an assembled document before the document is made available to the user.

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.

Receiving Data from a Webhook Code Examples

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

• Receiving Data When the Interview is Complete
• Getting External Answer Data During an Interview
• Getting External Answer Data When the Interview Loads
• Modifying a Document When the Interview is Complete