Web Hooks Overview
A web hook is a configurable function that sends a notification to an endpoint you specify when a particular event in Advance occurs.
For example, you can configure a web hook to send a notification to an endpoint in your own web application when a user completes a new work item version.
Overview
Web hooks enable Advance to notify your own web application when specific events occur in Advance. For example, when a user completes a new work item version. This is useful if you have an application that needs to perform an action based on the status of an entity in Advance. For example, you may have an application that must be notified when Advance creates new documents for a work item, so it can download those documents and save them in a document management system.
To work with Advance web hooks, your application must have an endpoint to which Advance can send data about the event. When the event occurs, the web hook sends a set of JSON data to your endpoint. For example, the data for a New Work Item Version Complete event includes the work item ID, name, the user that created the work item version, and the URL from which you can download the work item's assembled documents.
Your application must also manage access tokens, so that you can provide a token to Advance. Advance uses this token when sending event data to your application's endpoint, so that your application can authenticate the request.
Common Tasks
Among others, web hooks enable you to perform the following common tasks:
- View a Web Hook
- Create a Web Hook
- Editing a Web Hook
- Activating or Deactivating a Web Hook
- Deleting a Web Hook
- Connecting to an External Data Source Using the Custom Interview Event Web Hook
Workflow
You will typically create a web hook 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
- Token – an access token supplied by your application. The token specified in the web hook 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.
You must ensure that you can provide these items of information before you can create the web hook.
Event Types
The following event types are available when you create a web hook:
- New work item version complete
- Custom interview event
New Work Item Version Complete
The NewWorkItemVersionComplete event occurs when a user completes an assembly for an existing work item. This is 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 template component in the interview. This is useful if, for example, your users need to connect to external data sources.
Receiving Data from a Web Hook Code Example
See the Receiving Data from a Web Hook topic for information about receiving data from web hooks in your own application.