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:
- Navigate the folder structure of the external document provider
- Search files
- Link files into Workfront
- Upload files to the external document provider
- View a thumbnail for the document
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:
-
The user begins connecting the webhook integration to their account. Currently, this is done by clicking the “Add Document” dropdown > “Add Service” > Custom integration name.
-
Workfront navigates the user the Authentication URL, which may prompt the user to login to the external document provider. This page is hosted by the webhook provider or the external document management system. When doing so Workfront adds a “state” parameter to the Authentication URL. This value must be passed back to Workfront by appending the same value to the Workfront Return URI in the step below.
-
After logging to the external system (or if the user is already logged in), the user is taken to an “Authentication” page, which explains that Workfront is requesting access to perform a set of actions on the user’s behalf.
-
If the user clicks the “Allow” button, the browser will redirect to the Workfront Redirect URI , adding “code=
<code>
” to the querystring. Per the OAuth2 spec, this token is short lived. The querystring must also have the following, “state=<sent_by_workfront>
”. -
Workfront processes this request and makes an API call to the Token Endpoint URL with the authorization code.
-
The Token Endpoint URL returns a refresh token and access token.
-
Workfront stores a these tokens and fully provisions the webhook integration for this user.
-
From this point forward, Workfront will be able to make authorized API calls to the webhook provider. When making these calls, Workfront will send the the access token in the HTTP request header as shown below:
code language-none ------------------------------- Authorization: Bearer [access_token] -------------------------------
-
If the access token has expired, Workfront will make a call to the Token Endpoint URL to retrieve a new access token then attempt the authorized API call again with the new access token.
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
The ID of file or folder, as referenced by the webhook provider. This is different than Workfront's document ID. To get the metadata of the root directory, use the value '/'.
Note: The maximum length for the ID is 255 characters.
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":"20140605T17: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":"20140605T17: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":"20140605T17: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":"20140605T17: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:
-
Include an error code in the response header. Error codes include:
- 403 - Forbidden. Indicates that either the request tokens are missing or invalid, or that credentials associated with the tokens don’t have access to the specified resource. For OAuth-based webhook providers, Workfront will attempt to retrieve new access tokens.
- 404 - Not found. Indicates that the specified file or folder doesn’t exist.
- 500 - Internal Server Error. Any other type of error.
-
Describe the error in the response body using the following format:
{
"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:
- A Workfront account with Advanced Document Management (ADM) enabled
- A Workfront user for this account with System Admin rights
- A Document Webhook instance, who’s HTTP endpoints are accessible to Workfront
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.
- In Workfront, Go to the main Documents page by clicking on the Documents link in the top navigation bar.
- Click on the Add Documents dropdown and select your Document Webhook service under Add Service.
- (OAuth services only) After completing the previous step, you will see your service’s OAuth2 authentication page load load in a popup window. (Note: you may be prompted to login to your service first.) From the authentication page, grant Workfront access to the user’s account by click the Trust or Allow button.
- Verify your service has been added to the Add Documents dropdown. If you don’t see it initially, try refreshing your browser.
Test 2: Link a document into Workfront Tests the following endpoints: /files, /metadata
- In Workfront, Go to the main Documents page by clicking on the Documents link in the top navigation bar.
- Select your Document Webhook service under Add Documents.
- From the modal, navigate through the folder structure.
- Verify your able to navigate the folder structure properly.
- Select and link a document into Workfront
Test 3: Navigate to a document in the content management system
Tests the following endpoints: /metadata (specifically the viewLink)
- Link a document into Workfront
- Select the document and click the Open link.
- Verify that the document opens in a new tab.
Test 4: Navigate to a document in the content management system (with login)
Tests the following endpoints: /metadata (specifically the viewLink)
- Ensure that you are logged out of the content management system.
- Link a document into Workfront.
- Select the document and click the Open link.
- Verify that content management system’s login screen loads in a new tab.
- Login and verify that you’re taken to the document
Test 5: Download the document from the content management system
Tests the following endpoints: /metadata (specifically the downloadLink)
- Link a document into Workfront.
- Select the document and click the Download link.
- Verify that the download begins.
Test 6: Search for content
Tests the following endpoints: /search
- In Workfront, Go to the main Documents page by clicking on the Documents link in the top navigation bar.
- Select your Document Webhook service under Add Documents.
- From the modal, perform a search.
- Verify that the search results are correct.
Test 7: Send document from Workfront to content management system
Tests the following endpoints: /files, /uploadInit, /upload
- In Workfront, Go to the main Documents page by clicking on the Documents link in the top navigation bar.
- Upload a document to Workfront from your computer
- Go to the document details page
- From the Document Actions dropdown, select your Document Webhook service under Send To…
- Go to the desired destination folder and click the Save button.
- Verify that the document is uploaded to the correct location in the content management system.
Test 8: View Thumbnails in Workfront
Tests the following endpoints: /thumbnail
- Link a document into Workfront.
- Select the document in the list.
- Verify that the thumbnail appears in the right panel.
Test 9: Get the content bytes
Tests the following endpoints: /download
- Link a document into Workfront.
- Go to the document details page.
- Send the document to Workfront by selecting Document Actions > Send To… > Workfront. This will create a new document version in Workfront.
- Download the document from Workfront by clicking on the Download link.
Test 10: Refresh access token (OAuth2 Webhook providers only)
Tests the following endpoints: Token Endpoint URL
- Provision a the Document Webhook service for a user
- Invalidate the user’s access token by either 1 )waiting for it to timeout, or 2) invalidating it manually in the external system.
- Refresh the access token in Workfront. You can do this, for example, by linking a document into Workfront. You will know that the access token refreshed successfully if you were able to navigate to and link a document.
Versions
-
Version 1.0 (Release Date - May, 2015)
- Initial Specification
-
Version 1.1 (Release Date - June, 2015)
- Updated /uploadInit - Added documentId and documentVersionId
-
Version 1.2 (Release Date - October, 2015)
- Added /createFolder