Go to section …

Thread actions

Threads can specify custom actions for the thread’s external resource. Actions follow the schema.org Action format. Two types of actions are supported: ViewAction and UpdateAction. Actions enable you to create bidirectional integrations with CA Flowdock.

ViewAction

ViewActions are simply links that are shown in the thread’s list of actions.

Example ViewAction in a thread message

{
    "@type": "ViewAction",
    "url": "https://github.com/flowdock/component/pull/42/files",
    "name": "Diff",
    "description": "View diff in GitHub"
}

UpdateAction

UpdateActions allow for bi-directional integrations. Users can perform simple actions securely from CA Flowdock without opening new browser tabs. The integration will receive a request from CA Flowdock with the user’s CA Flowdock user ID (for authentication) to perform actions on the resource. Text input from the user is currently not supported.

Examples on how to handle the requests coming from UpdateActions can be found in How to create bidirectional integrations.

Example UpdateAction in a thread message

{
    "@type": "UpdateAction",
    "name": "Assign to me",
    "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://my-flowdock-app-integrator.com/issues/42?assignee=me",
        "httpMethod": "POST"
    }
}

UpdateAction requests made by CA Flowdock

Once CA Flowdock receives the thread message with UpdateActions, it converts the target’s urlTemplate into a signed CA Flowdock URL. When a CA Flowdock user selects the action, CA Flowdock will perform the specified request to the resource. The action payload data is the same as in the thread data, enriched with agent data that contains information about the CA Flowdock user that is performing the action.

Example action request from CA Flowdock

{
    "@type": "UpdateAction",
    "name": "Assign to me",
    "agent": {
        "@type": "Person",
        "name": "John Doe",
        "image": "https://cloudfront.com/avatar/url/120"
    },
    "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://my-flowdock-app-integrator.com/issues/42?assignee=me",
        "httpMethod": "POST"
    }
}

CA Flowdock user ID and request signature

The ‘FLOWDOCK-TOKEN’ header is an encoded token that contains the user’s CA Flowdock ID, expiration time and a signature of the request body. The token is encoded with JWT using the OAuth client secret as a signing key.

Example of a decoded FLOWDOCK-TOKEN header
{
    "sub": "<flowdock_user_id>",
    "exp": "<expiration time (30 seconds)>",
    "signature": "<SHA256 digested request body>"
}

Authentication challenge

If the application needs the user to authenticate in order to complete the action, the application should respond to the user’s action with a 401 status code and a URL where the user can perform the authentication. The user will be instructed to open this URL in his browser as the result of the failed action.

The authentication challenge must specify the authentication URL inside the 'www-authenticate’ header in the following format:

www-authenticate = "Flowdock-Token url=https://my-flowdock-app-integrator.com/authenticate"