�۶���Ƶ

Webhooks

A webhook is an HTTP call that is triggered by an event. You can use webhooks to activate instant trigger modules. Any application that is connected to the Internet and allows HTTP requests can send webhooks to �۶���Ƶ Workfront Fusion.

Access requirements

You must have the following access to use the functionality in this article:

*To find out what plan, license type, or access you have, contact your Workfront administrator.

**For information on �۶���Ƶ Workfront Fusion licenses, see �۶���Ƶ Workfront Fusion licenses

Use a webhook in Workfront Fusion

To use a webhook to connect an app to Workfront Fusion:

After you create a webhook, a unique URL displays. This is the address where the webhook sends data. Workfront Fusion validates the data sent to this address, then passes it on for processing in the scenario.

Configure the webhook’s data structure configure-the-webhook-s-data-structure

In order to recognize the data structure of the incoming payload, Workfront Fusion parses sample data that you send to the displayed address. You can supply the sample data by making a change in the service or app that will make that service or app call the webhook. For example, you could remove a file.

Or you can follow the steps below to send the sample data via the HTTP > Make a request module.

The webhook queue

If a webhook receives data and there is not an active scenario that is expecting that data, the data is stored in the queue. Once you activate the scenario, it processes all bundles waiting in the queue sequentially.

Supported incoming data formats

Workfront Fusion supports 3 incoming data formats: Query String, Form Data and JSON.

Workfront Fusion validates all incoming data against the selected data structure. Then, depending on the scenario’s settings, the data is either stored in the queue for processing, or it is processed immediately.

If any part of the data does not pass the validation, Workfront Fusion returns a 400 HTTP status code and specifies, in the body of the HTTP response, the reason why the incoming data failed the validation checks. If the validation of the incoming data succeeds, Workfront Fusion returns a “200 Accepted” status.

Query String

GET https://app.workfrontfusion.com/wh/<yourunique32characterslongstring>?name=<yourname>&job=automate

Form Data

POST https://app.workfrontfusion.com/wh/<yourunique32characterslongstring>

Content-Type: application/x-www-form-urlencoded

name=<yourname>&job=automate

Multipart form data

POST https://app.workfrontfusion.com/wh/<yourunique32characterslongstring>


Content-Type: multipart/form-data; boundary=---generatedboundary

---generatedboundary

Content-Disposition: form-data; name="file"; filename="file.txt"


Content-Type: text/plain


Content of file.txt


---generatedboundary

Content-Disposition: form-data; name="name"

Workfront Fusion

---generatedboundary

In order to receive files encoded with multipart/form-data, you must configure a data structure with a collection type field that contains the nested fields name, mime, and data. The field name is a text type and contains the name of the uploaded file. The mime is a text type and contains a file in MIME format. The field data is a buffer type and contains binary data for the file being transferred.

For more information on MIME format, see MIME modules.

JSON

POST https://app.workfrontfusion.com/wh/<yourunique32characterslongstring>

Content-Type: application/json

{"name": "Workfront Fusion", "job": "automate"}

Webhook headers

To access the webhook’s headers, enable Get request headers when setting up the webhook.

You can extract a particular header value with the combination of map() and get() functions.

INFO

Example:

The example below shows a formula that extracts the value of the authorization header from the Headers[] array. The formula is used in a filter that compares the extracted value with the given text to pass only webhooks if there is a match.

For further information on obtaining an array’s element with a given key, see Map an array’s element with a given key in the article Map information from one module to another in �۶���Ƶ Workfront Fusion.

Responding to webhooks

The default response to a webhook call is the text “Accepted”. The response is returned to the app that called the webhook during the execution of the Custom Webhook module.

Test the response to a webhook

If you want to customize the webhook’s response, employ the module Webhook Response.

The configuration of the module contains two fields: Status and Body.

Timeout for sending a response is 40 seconds. If the response is not available within that period, Workfront Fusion returns a ‘200 Accepted’ status.

HTML Response example

INFO

Example:

Configure the Webhook Response module as follows:

table 0-row-2 1-row-2 2-row-2 layout-auto html-authored no-header
Status	2xx success HTTP status code, e.g. 200
Body	HTML code
Custom headers	Key: Content-type Value: text/html

This will produce an HTML response that displays in a web browser:

Redirect example

INFO

Example: Configure the Webhook Response module as follows:

table 0-row-2 1-row-2 layout-auto html-authored no-header
Status	3xx redirection HTTP status code, e.g. 303
Custom headers	Key: Location Value: The URL you would like to redirect to.

Webhook deactivation

Webhooks are deactivated automatically if either of the following applies:

Deactivated webhooks are deleted and unregistered automatically if they are not connected to any scenarios and have been in deactivated status for over 30 days.

Troubleshooting

Missing items in the mapping panel

If some items are missing in the mapping panel in the setup of the modules following the Webhooks > Custom Webhook module, click on the Webhooks > Custom Webhook module to open its setup and click Re-determine data structure:

Then follow the steps described in the section Configure the webhook’s data structure in this article.