Document Webhooks API

Last update: February 7, 2025

CREATED FOR:

  • Developer

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:

Field NameDescription
NameThe name of this integration.
Base API URLThe location of the callback API. When making calls to the external system,Workfront will simply append the endpoint name to this address. For example, if the admin entered the Base API URL, " https://www.mycompany.com/api/v1 ", Workfront would using the following URL to get a document's metadata: https://www.mycompany.com/api/v1/metadata?id=1234.
Request parametersOptional values to be appended to the querystring of every API call. For example, access_type=offline.
Authentication TypeOAuth2 or ApiKey
Authentication URL(OAuth2 Only) The full URL used for user authentication. Workfront will navigate users to this address as part of the OAuth provisioning process. Note: Workfront will append a "state" parameter to the query string. The provider must pass this back to Workfront by appending it to the Workfront Redirect URI.
Token Endpoint URL(OAuth2 Only) The full API URL used to retrieve OAuth2 tokens. This is hosted by the webhook provider or external document provider
Client ID(OAuth2 Only) The OAuth2 Client ID for this integration
Client Secret(OAuth2 Only) The OAuth2 Client Secret for this integration
Workfront Redirect URI(OAuth2 Only) This is a read-only field and is generated by Workfront. This value is used to register this integration with the external document provider. Note: As described above for Authentication URL, the provider must append the "state" parameter and its value to the querystring when performing the redirect.
ApiKey(ApiKey Only) Used to make authorized API calls to the webhook provider. The API key issued by the webhook provider.

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:

  1. 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.

  2. 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.

  3. 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.

  4. 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>”.

  5. Workfront processes this request and makes an API call to the Token Endpoint URL with the authorization code.

  6. The Token Endpoint URL returns a refresh token and access token.

  7. Workfront stores a these tokens and fully provisions the webhook integration for this user.

  8. 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:

    -------------------------------
Authorization: Bearer [access_token] ­­­­­­­­­­­­­­­­­­­­­­­­­­
-------------------------------

  9. 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.