Document Webhooks API

Adobe Workfront Document Webhooks defines a set of API endpoints through which Workfront makes authorized API calls to an External Document Provider. This allows anyone to create a middleware plugin for any document storage provider.

The user experience for webhook-based integrations will be similar to that of existing document integrations, such as Google Drive, Box, and Dropbox. For example, a Workfront user will be able to perform the following actions:

Reference Implementation

To help jumpstart the development of a new webhooks implementation, Workfront provides a reference implementation. Code for this can be found at https://github.com/Workfront/webhooks-app. This implementation is Java-based and allows Workfront to connect documents on a network file system.

Registering a Webhook Integration

Workfront administrators can add a custom webhook integration for their company by navigating to Setup > Documents > Custom Integrations within Workfront. From the Custom Integration page within Setup, administrators can view a list of existing document Webhook integrations. From this page, integrations can be added, edited, enabled, and disabled. To add an integration, click the “Add Integration” button.

Available Fields

When adding an integration, the administrator will enter values for the following fields:

Authentication

Workfront document webhooks supports two different forms of authentication: OAuth2 and ApiKey. In both cases, Workfront passes authentication tokens in the header when making an API call.

OAuth2

OAuth2 allows Workfront to make authorized API calls to a webhook provider on behalf of a user. Before doing so, the user must connect their external document provider account to Workfront and grant Workfront

access to act on their behalf. This handshaking process only happens once for each user. Here’s how it works:

ApiKey

Making authorized API calls to a webhook provider using an ApiKey is much simpler than OAuth2. When making an API call, Workfront will simply pass the ApiKey and Workfront username in the HTTP request header:

-------------------------------

apiKey: 12345

username: johndoe@foo.com

-------------------------------

The Webhook provider can use the username to apply user-specific permissions. This works best when both systems connect to LDAP using Single Sign On (SSO).

Adding Request Headers (optional)

In addition to using either OAuth2 tokens or an ApiKey for authentication, Workfront can send a predefined set of headers to the webhook provider for every API call. A Workfront administrator can setup set this up when registering or editing a Webook Integration, as described in the section above. See Registering a Webhook Integration.

For example, this can be used for Basic Authentication. To do this, the Workfront administrator would add the following Request Header information in the Custom Integration dialog:

Authorization Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

where QWxhZGRpbjpvcGVuIHNlc2FtZQ== is a base-64 encoded string of “username:password”. See Basic Authentication . Provided that this added, Workfront will pass this in the HTTP request header, in addition to other request headers:

­­­­­­­­­­­­­­­­­­­­­­­­­­-------------------------------

apiKey: 12345

username: johndoe@foo.com

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ== ­­­­­­­­­­­­­­­­­­­­­­­­­­

-------------------------------

API Specification

Below is a list of APIs that the webhook provider should implement in order for document webhooks to work.

Getting OAuth2 Tokens (needed OAuth2 authentication only)

Returns the OAuth2 refresh token and access token for an authenticated user. This is invoked once when the the user provisions a Document Provider. Subsequent calls are made to get an updated access token.

HTTP Request POST /any/url

The URL is configurable and corresponds to the Token Endpoint URL value on the custom integration Setup page.

Query Parameters

Response

Example

POST /oauth2/token
grant_type=authorization_code
code=d9ac7asdf6asdf579d7a8
client_id=123456
client_secret=6asdf7a7a9a4af

Response

{
"access_token":"ad8af5ad5ads759",
"refresh_token":"9a0h5d87d808ads",
"expires_id":"3600"
}

Get metadata for file or folder

Returns metadata for the specified file or folder.

URL

GET /metadata?id=[document or folder ID]

Query Parameters

Response

Example: https://www.acme.com/api/metadata?id=12345

Response

{
"title":"My Document",
"kind":"file"
"id":"12345",
"viewLink":"https://www.acme.com/viewDocument?id=12345",
"downloadLink":"https://www.acme.com/downloadDocument?id=12345",
"mimeType":"image/png",
"dateModified":"2014­06­05T17:39:45.251Z",
"size": "32554694"
}

Get a list of items in a folder

Returns metadata for the files and folders for a given folder.

URL

GET /files

Query Parameters

The Document Webhooks API does not currently support pagination.

Response

JSON containing a list of files and folders. The metadata for each item is the same that returned by the /metadata endpoint.

Example: https://www.acme.com/api/files?parentId=123456

Response

[
{
"title":"Folder A",
"kind":"folder",
"id":"2lj23lkj",
"viewLink":"https://www.acme.com/viewDocument?id=2lj23lkj",
"downloadLink":"https://www.acme.com/downloadDocument?id=2lj23lkj",
"mimeType":"",
"dateModified":"2014­06­05T17:39:45.251Z",
"size":""
},
{
"title":"My Document",
"kind":"file",
"id":"da8cj234"
"viewLink":"https://www.acme.com/viewDocument?id=da8cj234",
"downloadLink":"https://www.acme.com/downloadDocument?id=da8cj234",
"mimeType":"image/png",
"dateModified":"2014­06­05T17:39:45.251Z",
"size":"32554694"
},
]

Do a Search

Returns metadata for the files and folders returned from a search. This can be implemented as a full-text search or as a regular database query. Workfront calls the /search endpoint when the user performs a search from the external file browser.

URL

GET /search

Query Parameters

The Document Webhooks API does not currently support pagination.

Response

JSON containing a list of metadata for files and folders matching the query. What constitutes a “match” is determined by the webhook provider. Ideally, it should do a full-text search. Doing a filename-based search also works.

Example: https://www.acme.com/api/search?query=test-query

Response

[
{ File/Folder Metadata },
{ File/Folder Metadata }
]

Get the content of a document

Returns the raw bytes for a document

URL

GET /download

Query Parameters

Response

The raw bytes of the document.

Example: https://www.acme.com/api/download?id=123456

Get a thumbnail for a document

Returns the raw thumbnail bytes for a document.

URL

GET /thumbnail

Query Parameters

Response

The raw thumbnail bytes.

Example: https://www.acme.com/api/thumbnail?id=123456

Upload a file - Part 1 of 2

Uploading a file to a document storage provider is a two-step process that requires two separate API endpoint. Workfront begins the upload process by calling /uploadInit . This endpoint returns a document ID which is then passed to /upload when uploading the document bytes. Depending on the underlying document storage system, it may be necessary to create a zero-length document then update the contents of the document later.

Added to version 1.1 of this spec, the document ID and document version ID can be used to retrieve extra information from Workfront. For example, if the document management system wants extra information about the document, the webhook implementation code could use the document ID to retrieve that information using Workfront’s RESTful API. As a good practice, this information could come from custom data fields on the document and it’s containing task, issue, or project.

URL

POST /uploadInit

Query Parameters

Response

The metadata for the file, as defined by the /metadata endpoint.

Example: https://www.acme.com/api/uploadInit?parentId=12345&filename=new-file.png&docu mentId=511ea6e000023edb38d2effb2f4e6e3b&documentVersionId=511ea6e000023edb38d2e ffb2f4e6e3b

Response

[file_metadata] ­includes the new document ID used by the document provider.

Upload a file - Part 2 of 2

Uploads the bytes of a document to the webhook provider.

URL

PUT /upload

Query Parameters

Request Body

The raw content bytes for the document.

Response

{
"result": "success"
}

or

{
"result": "fail"
}

Example: https://www.acme.com/api/upload?id=1234 [document bytes included in update stream]

Response

{
"result":"success"
}

Get information about the service

(Release Date - TBD) Returns information about the service, such as features and capabilities. Workfront will use this information to customize the user interface in Workfront. For example, if the webhook implementation contains some custom actions, the JSON should list those operations in the JSON. Users would then be able to invoke these actions from Workfront.

URL

GET /serviceInfo

Query Parameters

None. In addition, calls to this endpoint should not require authentication.

Response

JSON containing information about this service

Example: https://www.acme.com/api/serviceInfo

Returns

{
"webhook version": "1.2", "version": "1.0", "publisher": "Acme, LLC", "availableEndpoints": ["files", "metadata", "search", "download"

"thumbnail", "uploadInit", "upload" ], "customActions" [
{
"name": "archive", "displayName": "Archive" }, {

"name": "doSomethingElse", "displayName": "Do Something" }, ] }

Create a Folder

(Added in version 1.2) Creates a folder in a given directory.
URL

POST /createFolder

Query Parameters

Response

The metadata for the newly created folder, as defined by the /metadata endpoint.

Example: POST https://www.acme.com/api/createFolder

-------------------------------

parentId=1234

name=New Folder ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­

-------------------------------

returns

{"title":"New Folder",
 "kind":"folder""id":"5678",
 "viewLink":"",
 "downloadLink":"",
 "mimeType":"",
 "dateModified":"2014­06­05T17:39:45.251Z"
 "size": ""
 }

Delete a Document or Folder

(Release Date - TBD) Deletes a document or folder with the given ID in the external system. Deleting a folder will also delete its contents.

URL

PUT /delete

Query Parameters

Response A JSON string indicating success or failure, as specified in the Error Handling section below.

Example: PUT https://www.acme.com/api/delete ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­ id=1234 ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­

returns

{
"status": "success"
}

returns

{
"status": "failure", "error": "File not found"
}

Rename a Document or Folder

(Release Date - TBD) Renames a document or folder with the given ID in the external system.

URL

PUT /rename

Query Parameters

Response

A JSON string indicating success or failure, as specified in the Error Handling section below.

Example:

PUT https://www.acme.com/api/rename

-------------------------------

id=1234

name=Folder B ­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­­

-------------------------------

{
"status": "success"
}returns
{
"status": "failure", error: "Folder cannot be renamed because a folder with that name already exists."
}

Perform a Custom Action

(Release Date - TBD) This endpoint will allow a Workfront user (or perhaps an automated workflow event) to perform an action in the external system. The /customAction endpoint accepts a “name” parameter, which allows the webhook provider to implement multiple custom operations.

The webhook provider registers custom actions with Workfront by including the actions in the /serviceInfo response under customActions. Workfront loads this list when setting up or refreshing the webhook provider under Setup > Documents > Custom Integrations.

Users can trigger the custom action by selecting the section under “Document Actions”

URL

GET /customAction

Query Parameters

Response

A JSON string indicating success or failure, as specified in the Error Handling section below. On failure (i.e. status = “failure”), Workfront will display the provided error message to the user.

Example: https://sample.com/webhooks/customName?name=archive&documentId=5502082c003a4f30 ddec2fb2b739cb7c&documentVersionId=54b598a700e2342d6971597a5df1a8d3

response

{
"status": "success"
}

Error Handling

Problems may arise when processing API requests. This should handled in a consistent way across across all API endpoints. When an error occurs, the webhook provider do the following:

{
"status": "error"
"error": "Sample error message"
}

Testing

To verify that your document webhook implementation works correctly, run the following tests. These are manual tests that go through the Workfront web interface and indirectly hit the endpoints for your webhook implementation.

Prerequisites

To run these tests you will need the following:

These tests also assume that you’ve already registered your Document Webhook instance in Workfront under Setup > Documents > Custom Integrations.

Test 1: Provision the Document Webhook service for a user

Tests the Authentication URL and Token Endpoint URL for OAuth-based Webhook providers.

Test 2: Link a document into Workfront Tests the following endpoints: /files, /metadata

Test 3: Navigate to a document in the content management system

Tests the following endpoints: /metadata (specifically the viewLink)

Test 4: Navigate to a document in the content management system (with login)

Tests the following endpoints: /metadata (specifically the viewLink)

Test 5: Download the document from the content management system

Tests the following endpoints: /metadata (specifically the downloadLink)

Test 6: Search for content

Tests the following endpoints: /search

Test 7: Send document from Workfront to content management system

Tests the following endpoints: /files, /uploadInit, /upload

Test 8: View Thumbnails in Workfront

Tests the following endpoints: /thumbnail

Test 9: Get the content bytes

Tests the following endpoints: /download

Test 10: Refresh access token (OAuth2 Webhook providers only)

Tests the following endpoints: Token Endpoint URL

Versions