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:
- View a Webhook
- Create a Webhook
- Editing a Webhook
- Activating or Deactivating a Webhook
- Deleting a Webhook
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.
Receiving Data from a Webhook Code Examples
See the following topics for information about receiving data from webhooks in your own web application:
- Using the New Work Item Version Complete Webhook to Receive Notifications
- Using the Custom Interview Event Webhook to Get Answers During Interview
- Using the Interview Load Event Webhook to Get Initial Answer Data
- Using the Post-assembly Processing Event Webhook to Modify Documents
- Using the Post-assembly Processing Event Webhook to Add Documents