Actions

An action in Gadget is a unit of work that your application can perform, like saving a record or processing a webhook. Actions define the behavior of the application.

How does an action work?

Actions execute as serverless JavaScript functions mounted inside the Gadget framework, triggered by one of Gadget's built-in triggers. Actions can be run by user interactions, API calls, incoming webhooks, all without having to write the standard boilerplate code to process requests, authorization, or responses. Actions remain fully customizable, allowing developers to implement custom logic like input validation, record updates, third-party API interactions, and more.

Types of actions

There are 2 types of actions in Gadget:

Model actions: API endpoints that run in the context of specific records within a model
Global actions: Run outside the context of any particular record

For more information, see the Types of Actions guide.

Action framework

Each model action and global action in Gadget follows the same pattern. A trigger starts an action, then permissions are checked, and then the action's handler functions are executed to do the actual work.

This is the specific sequence that Gadget runs:

A trigger starts the action. Triggers are often the GraphQL API mutation being run, but they can also be things like webhooks from 3rd parties or a daily cron-style scheduler. Think of triggers as the when of running an action.
Gadget verifies that the caller has permission to run the action. The current user or current API key's permissions determine whether or not the action can be run. Think of permissions as the answer to who can run an action. For more information on roles and permissions, see the access control guide.
Model actions load the record they are being run on from the database. You don't have to manually fetch the record that the action is running on.
The action's run function is executed within a database transaction. The run function can manipulate the record, make API calls, log data, or do anything else that needs to happen. Think of run as the what of an action.
If the run function succeeds and the database transaction commits, the Action's onSuccess function is then executed. onSuccess is a secondary function that only executes certain business logic if the run function succeeded. This is useful for the common case of doing work after webhooks from third-party systems like Shopify only after all the data is saved in run.

Global Actions share all these same properties, but since they don't operate in the context of a record, they don't load any data automatically.

Triggers

Triggers in Gadget are mechanisms that capture events from external sources, such as incoming webhooks or API calls, and initiate the execution of actions. They serve as the starting point for the action's workflow by parsing the event data and passing it along for further processing. Triggers can be pre-configured defaults, like the GraphQL API trigger or Shopify Webhook triggers, or they can be custom-defined based on specific requirements.

For more information on types of triggers see the Triggers guide.

Action code

Actions are each expressed in their own JavaScript file, which runs on Gadget's serverless Node.js hosting. Within the run and onSuccess functions in these files, actions can modify the database, make outbound API calls, change the user's session, or perform any other desired operations using the helpers from gadget-server or packages from npm.