Creating a Webhook

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

You can create a webhook in the Webhooks section of HotDocs Advance, accessed through the Configuration pane.

Prerequisites

  • Your own web application
  • An endpoint in that application to which you want to send event data
  • An access token provided by your application; this is used by Advance to authenticate requests sent to your application endpoint
  • The Custom Interview Event webhook has additional prerequisites.

To create a web hook

  1. In the Administration section, click Manage webhooksManage webhooks
  2. In the upper-right corner of the screen, click Create Create new webhook.
  3. Enter the following webhook details:
    • Name (required) – the webhook's name
    • URL (required) – the URL for the endpoint to which you want Advance to send event data
    • Event type (required) – select an event for the webhook from the following options:
      • NewWorkItemVersionComplete – sends event data when a user completes a new work item version
      • CustomInterviewEvent – sends event data when a template component is activated in an interview
      • InterviewLoadEvent – sends event data when a user opens an interview
      • PostProcessingEvent – sends event data when a user completes an assembly
    • Interview Event Name (required when CustomInterviewEvent is selected) – the Event Name of the Interview Event dialog element used in the template.
    • Authentication Method (required) – select an authentication method from the following options:
      • HMAC (default) – an HMAC code, provided by Advance; this is sent in the request form data (named "token").
      • Access token – an access token, provided by your application; this is sent in the Authorization header of the request sent to your application endpoint from Advance.
    • Payload Format - choose whether to use the standard or legacy payload format. Standard format is used by default.
    • Request verb (required when CustomInterviewEvent is selected) –  the HTTP request verb of the webhook. POST is the request verb default.
    • Webhook active status – select the Webhook active checkbox to set the state to active (default); inactive webhooks do not send event data to your endpoint.
    • Accepts untrusted SSL certificates – either Block untrusted SSL (default) or Accept untrusted SSL; accepting untrusted SSL allows the webhook to send data over HTTPS even when the SSL certificate is untrusted.
    • Work Groups (available when LoadInterviewEvent is selected) – select the work groups for which Advance activates the webhook.
    • Templates (available when LoadInterviewEvent is selected) – select the templates for which Advance activates the webhook.
  4. Click Create.

The new webhook appears in the Webhooks list.

The correct Request Verb for your webhook should be POST. If you have an existing webhook which uses a GET request verb, it is advised you edit the webhook to use POST.

Payload Formats

To avoid breaking webhooks when updating to future API versions, the standard payload format now only provides properties that you can use to build the URLs you need. To continue receiving the v1.1-specific response when the webhook is triggered, you can opt into using the legacy version. However, please note that as the legacy version responses contain the v1.1 version number you may still need to update your integration in future.

Next steps