Receiving Data from a Web Hook

This example explains how to receive data from a web hook for the New Work Item Version Complete event.

In this Topic ShowHide

Prerequisites
Your existing web hook
New Work Item Version Complete Event
Example JSON Response Data
Code Example
Testing your example application

Prerequisites

Creating a Web Hook – before you can receive data from a web hook, you must have an existing web hook.

Your existing web hook

This example supposes that you have an existing web hook with the following properties:

Name – WebHookExample01
URL – http://localhost/webhookexampleapplication/NewWorkItemVersion
Token – exampletoken
Event – New Work Item Version Complete (sends event data when a user completes a new work item version)
Active Status – Active
Untrusted SSL certificates – No

The URL for the web hook should point at the endpoint we are going to create in our example application. You can go back and edit the URL for the web hook after creating the example application, if necessary.

Token

The token specified in the web hook is passed in the response sent to your endpoint, in the Authorization header. You should always authenticate responses from Advance in your own application, using this token.

New Work Item Version Complete Event

Web hooks configured to use the NewWorkItemVersionComplete event run when a user in Advance completes a new version of a work item, usually when a user finishes a work item's interview. Finishing the interview typically results in Advance producing a new set of documents for the work item. When the new work item version is complete, Advance sends a set of event data to the endpoint you specified when creating the web hook.

This event is useful as it notifies you when a new set of documents is available for a work item. For example, this enables you to download the completed documents and send them to another system (e.g. a document management system).

Example JSON Response Data

The following JSON data is an example of the response expected from a New Work Item Version Complete event.

{
    "eventId":"d395c096-5ca0-4225-8542-6ba313b93c96",
    "eventType":"NewWorkItemVersionComplete",
    "createdDate":"2018-10-31T13:13:13.8096177Z",
    "createdBy":{
        "id":"c955a8fa-cd7a-413e-811b-fe8618121cba",
        "loginName":"john.smith@example.com",
        "accountType":"UserAccount"
    },
    "data":{
        "workItemId":"af8cee70-e59d-4a00-8b97-aa771f8b6ab9",
        "workItemVersionId":"20a06ea2-e6b3-4b04-bbeb-93913d4db9e4",
        "workItemName":"WI001",
        "documents":[{
            "id":"f8315acd-a2fa-5366-bca0-813f47c4b81c",
            "name":"Example Contract",
            "url":"https://advance.yourdomain.com/HdaApi/rest/v1.1/workitems/af8cee70-e59d-4a00-8b97-aa771f8b6ab9/documents/f8315acd-a2fa-5366-bca0-813f47c4b81c/content"
        }],
        "templateVersionId":"9767ee0b-5ec1-5903-8c25-0d1428fcc27b",
        "templateVersionName":"Example Contract"
    },
    "relativeTimestamp":12
}

In the example you will create several classes to represent this set of data.

Code Example

C#

Note: this code example assumes that you are using .Net Framework 4.6 and a new ASP.NET Web Application project. It also assumes you have completed the Getting an Access Token using the Resource Owner Flow topic and can retrieve an access token.

NewWorkItemVersion.cs

This class represents the data you will receive from the web hook about the new work item version. For simplicity, we will define multiple classes within the same file.

using System;


namespace WebHookExampleApplication
{
    public class NewWorkItemVersion
    {
        public Guid EventId { get; set; }
        public string EventType { get; set; }
        public DateTime CreatedDate { get; set; }
        public User CreatedBy { get; set; }
        public WorkItem Data { get; set; }
        public string RelativeTimeStamp { get; set; }
    }

    public class User
    {
        public Guid Id { get; set; }
        public string LoginName { get; set; }
        public string AccountType { get; set; }
    }

    public class WorkItem
    {
        public Guid WorkItemId { get; set; }
        public Guid WorkItemVersionId { get; set; }
        public string WorkItemName { get; set; }
        public Document[] Documents { get; set; }
    }

    public class Document
    {
        public Guid Id { get; set; }
        public string Name { get; set; }
        public string Url { get; set; }
        public Guid TemplateVersionId { get; set; }
        public string TemplateVersionName { get; set; }
    }
}

HomeController.cs

This class contains the endpoint ("NewWorkItemVersion") to which Advance posts data about the new work item version. When Advance posts the data to the endpoint, it downloads the new documents for the work item.

using System.Web.Mvc;
using System.Threading.Tasks;

namespace WebHookExampleApplication.Controllers
{
    public class HomeController : Controller
    {
        [HttpPost]
        public async Task NewWorkItemVersion(NewWorkItemVersion newWorkItemVersion)
        {
            // Document URLs
            var documentUrls = newWorkItemVersion.Data.Documents;
            // Get the access token for making API requests

            // See Getting an Access Token using the Resource Owner Flow for more information.
	var token = await new ResourceOwnerAuthorization().GetResourceOwnerToken();

	// Download documents 
	var downloader = new DocumentsDownloader(); 
	await downloader.DownloadAsync(token, urls);
        }
    }
}

DocumentsDownloader.cs

This class downloads the new documents from the work item.

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
 
namespace WebHookExampleApplication
{
    public class DocumentsDownloader
    {
        public async Task DownloadAsync(string token, Document[] documents)
        {
            using (var client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
                foreach (var document in documents)
                {
                    // Download the document
                    var request = CreateHttpRequestMessage(document.Url);
                    var response = await client.SendAsync(request);
                    await SaveDocument(response);
                }
            }
        }
 
        private HttpRequestMessage CreateHttpRequestMessage(string documentUrl)
        {
            return new HttpRequestMessage
            {
                RequestUri = new Uri(documentUrl),
                Method = HttpMethod.Get
            };
        }
 
        private async Task SaveDocument(HttpResponseMessage response)
        {
            using (Stream output = File.OpenWrite(string.Format(@"C:\temp\{0}.docx", Guid.NewGuid()))) {
                await (await response.Content.ReadAsStreamAsync()).CopyToAsync(output);
                output.Close();
            }
        }
    }
}

Testing your example application

In Visual Studio, run your example application.
When the application opens in your web browser, make a note of the URL. For example, https://localhost/webhookexampleapplication/
Open Advance and look at your web hook; ensure the web hook URL matches the URL of your application (including the endpoint name). For example, https://localhost/webhookexampleapplication/newworkitemversion.
In Advance, create a new work item.
Once the interview for the work item is complete, you should see an assembled document appear in your C:\temp folder.