> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.staging.frame.io/platform/v4/docs/guides/custom-actions/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.staging.frame.io/_mcp/server. # Custom Actions Beta Frame.io Actions provide quick access to common media operations like downloading, renaming, and duplicating items – and also allow for integrations with 3rd party tools and services to be surfaced directly within the user interface of [Frame.io](https://next.frame.io/). ## About Actions With the introduction of custom Actions (beta), developers can configure and manage their own Actions in Frame.io V4. Leveraging the same underlying Event system as [Webhooks](https://developer.adobe.com/frameio/guides/Webhooks/), custom Actions are an alternative mechanism for developers to connect their assets to the tools that matter most to the users in their Frame.io Account. Actions can be executed by any user that is a Member of the Frame.io Workspace the Action is enabled in. When executing an Action, Frame.io sends a payload to a URL you provide. The receiving application responds with an HTTP status code to acknowledge receipt, or with a custom callback to render additional form fields in the Frame.io UI. The receiving application can be your own hosted program, service, or even low-code/no-code IPaaS tool like Workfront Fusion or Zapier. Use the Custom Actions beta to build integrations directly into [Frame.io](https://next.frame.io/) as programmable UI components. This enables workflows that can be triggered by users within the app, leveraging the same underlying events routing as webhooks. You can create user-triggered single or multi-step forms that come back to Frame.io as another form or a basic response. And when a user clicks a Custom Action on an Asset, Frame.io sends a payload to a URL you provide. The receiving application responds with an HTTP status code to acknowledge receipt, or responds with a custom callback that can render additional UI in Frame.io. ## Actions Improvements in V4 Leveraging learnings from users of our Legacy version, we've included a number of enhancements to the Actions feature set in Frame.io V4: #### New Field Types Previously limited to text and single-select fields, we now support multi-select, text area (for a larger text box) and a boolean field (for a radio button) as well. #### Clickable Links Text fields don't make it easy for users to copy/paste URLs. Use our new link field to get an easy, 1-click to copy experience instead. #### Dynamic Modals Depending on the amount of data returned, you can trust your Action's modal to dynamically resize to best fit the information in your form, including scrollable modals when needed. ## Migrated Actions There are a few things to keep in mind when migrating to a Frame.io V4 Account containing custom Actions previously created in the legacy version of Frame.io. ### Action Status Upon Account migration to Frame.io V4, all custom Actions created in earlier versions will have a status of 'null' and will be automatically disabled. This provides users the opportunity to first update your Actions to use the V4 API before enabling as any Actions not updated will fail. To identify Actions in this state visit the Actions Settings page and reference the column "Status" or, if using the API, by checking the is\_active field. ### Actionable Resources: Files, Folders & Version Stacks Given the separation of asset types as separate resources in the Frame.io V4 API, there may be behavior to consider when interpreting the resource ID received in your Action's payload. The behavior for individual Files is straight-forward, as the ID will reflect the specific File the Action was executed on. Likewise for Folders, you'll be receiving the ID for the Folder the Action was executed on; however, depending on your use-case you have multiple options when defining your Action's behavior. Use the Folder ID to make subsequent calls to the Frame.io API if you want interact with the Folder resource itself. Alternatively, you may want to get the children of that Folder in order to perform further processing on the assets within. When an action is Executed on a Version Stack, your payload will contain the ID for the 'Head Asset', which is the top most File in the Stack and is what is shown in the Frame.io UI. You can read more about the differences between the Frame.io Legacy API and V4 in our [Migration Guide](https://developer.adobe.com/frameio/guides/Migration/). > **Info** > > Configure [Custom Actions](https://developer.staging.adobe.com/platform/v4-experimental/api-reference/custom-actions/actions-show) in the Experimental API. A Custom Action requires: | Field name | Description | | ----------- | ----------------------------------------------------------------------------------------------------------------- | | Name | The name you choose for your custom action. It will be shown in the menu of available custom actions in Frame.io. | | Description | Explain what the action does, for reference (the description won't appear in the Frame.io web app). | | Event | Internal event key to help you differentiate between standard webhook events and your own. | | URL | Where to deliver events. | | Workspace | The Workspace that will use the custom action. | ## Configure Your Custom Action When a user selects a Custom Action on an Asset, Frame.io sends a payload to a URL you provide. The receiving application can respond with an HTTP status code to acknowledge receipt, or respond with a custom callback that renders additional UI in [Frame.io](https://next.frame.io/). > **Warning** > > Content Admin permissions are required to create Custom Actions for a Workspace. Ask your admin to modify your permissions if you don't have access. ## Payload From Frame.io When the user clicks your Custom Action, a payload is sent to the URL you set in the URL field. Use this payload to identify: #### Action Context * Which Custom Action was clicked * Which resource was clicked * Which user took the action * Which event type was triggered #### Organization Context * Which account is associated with the Custom Action * Which Workspace is associated with the Custom Action * Which Project contains the resource ```json POST /your/url { "account_id": "9a44f696-ae69-4e0c-9731-806d27ea46f1", "action_id": "ecd40785-4485-4f07-9d26-a006ea84efdf", "interaction_id": "e0a1c945-a8da-480d-92fb-e895cb640a01", "project": { "id": "3dda6833-ec3b-46bd-a7d9-1a77c03a165b" }, "resource": { "id": "f9d5728c-ac1a-4f48-92bb-ea2f9be3c58b", "type": "file" }, "type": "two.event", "user": { "id": "50d976e6-27d2-47cb-9388-45b38d55f4f0" }, "workspace": { "id": "382a1fe6-67cf-481e-9b65-79cfd9e9727f" } } ``` | Field name | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | The unique account of this Action. It is always be the same for a given Action. | | `action_id` | The unique id of this Action. It is always be the same for a given Action. | | `interaction_id` | This is a unique identifier generated by Frame.io that you can use to keep track of your transaction. This identifier is the same throughout any sequence of an Action, including callback forms. | | `project_id` | The unique project of this Action. It is always be the same for a given Action. | | `resource.id` | The id of the resource from which you triggered your Action (usually an Asset). | | `resource.type` | The type of resource from which you triggered your Action (usually **asset**) It can be `file`,`folder` or `version_stack`. | | `type` | The name of the event you put in the Event field when configuring your Action. | | `user.id` | The unique ID to identify the user who triggered the action. | | `workspace.id` | The unique Workspace of this Action. It is always be the same for a given Action. | | `data` | An object of key-value pairs denoting the name of a form element and the value selected and is what the user defines to inform the client url app of a choice being made. | ## Interactions, Retries and Timeouts The `interaction_id` is a unique identifier to track of the interaction as it evolves over time. If you do not need to respond to the user, return a 200 status code, and you're done. While optional, we recommend including information about the result of the action, like a success message or error alert. Custom actions support message callbacks. > **Note** > > Frame.io expects a response in less than 10 seconds, and attempts to retry up to 5 times while waiting for a successful response. Ideally the response is immediate and asynchronous actions occur after a trigger via a Custom Action. ## Create a Message Callback In your HTTP response to the webhook event, you can return a JSON object describing a message that will be returned to the initiating user in the Frame.io UI. ```json { "title": "Success!", "description": "The thing worked! Nice." } ``` Messages close the action loop providing variable context to the user, without asking them to switch contexts. When the initial payload and subsequent calls to the Frame.io API don't provide enough context for the receiving application, use **Form Callbacks**. ## Create a Form Callback Let's say that you need more info before you start your process. For example, you may be uploading content to a system that requires additional details and settings. You can describe a Form in your response, which the user sees snd fills out, and is then sent right back to you! Here's an example form that renders a Form in the Frame.io UI that the acting user can fill out and submit: ```json { "title": "Need some more info!", "description": "Getting ready to submit this file!", "fields": [ { "type": "text", "label": "Title", "name": "title", "value": "MyVideo.mp4" }, { "type": "select", "label": "Captions", "name": "captions", "options": [ { "name": "Off", "value": "off" }, { "name": "On", "value": "on" } ] } ] } ``` When the user submits the form, you'll receive an event on the same URL as the initial POST: ```json POST /your/url { "type": "your-specified-event-name", "interaction_id": "the-same-id-as-before", "action_id": "unique-id-for-this-custom-action", "data":{ "title": "MyVideo.mp4", "captions": "off" } } ``` All custom fields added on a form appear in the data section of the JSON payload sent by Frame.io. Use the `interaction_id` to map the initial request and this new form data. And again, you can respond with a message (or even another form!). By chaining Actions, Forms, and Messages, you can effectively program entire Asset workflows in Frame.io with business logic from an external system. ## Form Details Like messages, Forms support `title` and `description` attributes that render at the top of the Form. Beyond that, each form field accepts the following base attributes: #### Field Properties * **type** -- Tells the Frame.io UI which type of data to expect, and which component and render. * **label** -- Appears on the UI as the header above the field. #### Field Data * **name** -- Key by which the field will be identified on the subsequent payload. * **value** -- Value with which to pre-populate the field. ## Supported Field Types ### Text field A simple text field with no additional parameters. ```json { "type": "text", "label": "Title", "name": "title", "value": "MyVideo.mp4" } ``` ### Text area A simple text area with no additional parameters. ```json { "type": "textarea", "label": "Description", "name": "description", "value": "This video is really, really popular." } ``` ### Select list Defines a picklist that the user can choose from. Must include an `options` list, each member of which should include a human-readable `name`, and a machine-parseable `value`. ```json { "type": "select", "label": "Captions", "name": "captions", "value": "off", "options": [ { "name": "Off", "value": "off" }, { "name": "On", "value": "on" } ] } ``` ### Checkbox A simple checkbox with no additional parameters. ```json { "type": "boolean", "name": "enabled", "label": "Enabled", "value": "false" } ``` ### Link A simple link with no additional parameters. ```json { "type": "link", "name": "videoLink", "label": "Video Link", "value": "https://www.youtube.com/watch?v=XtX1zv9CEVc" } ``` ## The Frame.io Permissions Model Custom Actions have a special permissions model: they belong to a Workspace, not to any specific user who exists on an Account. That means: #### Creation & Management * Any Content Admin can create a Custom Action on a Workspace. * Any Content Admin can modify or delete a Custom Action that exists on a Team. #### Live Updates * Once modified, all users will immediately see the result of the change. ## Security and Verification By default, all Custom Actions have a signing key generated during their creation. This is not configurable. This key can be used to verify that the request originates from Frame.io. Included in the `POST` request are the following: | Name | Description | | ----------------------------- | ------------------------------------------ | | `X-Frameio-Request-Timestamp` | The time your Custom Action was triggered. | | `X-Frameio-Signature` | The computed signature. | #### Timestamp Verification **The timestamp** is the time the request was signed on its way out of Frame.io's network. This can be used to prevent replay attacks. We recommended verifying this time is within 5 minutes of local time. #### Signature Verification **The signature** is a HMAC SHA-256 hash using the signing key provided when the Custom Action is first created. ### Verifying the Signature #### Extract the signature Extract the signature from the HTTP headers. #### Create message to sign Create a message to sign by combining the version, delivery time, and request body `v0:timestamp:body`. #### Compute HMAC SHA256 Compute the HMAC SHA256 signature using your signing secret. #### Compare signatures Compare your computed signature with the provided one! > **Note** > > The provided signature is prefixed with `v0=`. Currently Frame.io only has this one version for signing requests. You will need to add this prefix to your computed signature. **`Python`** ```python title="Python" import hmac import hashlib def verify_signature(curr_time, req_time, signature, body, secret): """ Verify webhook/custom action signature :Args: curr_time (float): Current epoch time req_time (float): Request epoch time signature (str): Signature provided by the frame.io API for the given request body (str): Custom Action body from the received POST secret (str): The secret for this Custom Action that you saved when you first created it """ if int(curr_time) - int(req_time) < 500: message = 'v0:{}:{}'.format(req_time, body) calculated_signature = 'v0={}'.format(hmac.new( bytes(secret, 'latin-1'), msg=bytes(message, 'latin-1'), digestmod=hashlib.sha256).hexdigest()) if calculated_signature == signature: return True return False ``` ## Beta Feedback We'd love to hear from developers and end-users about the ways you'd like to use Actions in Frame.io V4. Be sure to [reach out to us](https://forum.frame.io/) with your questions, ideas, and use-cases to help inform our prioritization.