Gadget framework
Glossary
FAQ

Triggers 

What is a trigger? 

Triggers in Gadget are events or conditions that initiate an action within an application. They parse external events, such as incoming webhooks or API calls, and transmit them to the rest of the action. Default triggers are already established in many actions, such as the API endpoint trigger for integrating the action into your app's API or the Shopify webhook trigger that executes actions in response to Shopify webhooks.

How triggers work 

1. Condition that activates trigger: Each trigger is designed to execute at a specific point, determined by various conditions or events. For instance, a GraphQL API trigger executes when its corresponding mutation in the GraphQL API is invoked, while a Scheduler trigger activates at pre-set time intervals, akin to a cron job.

2. Output params sent to action: Upon activating, the trigger immediately assesses the permission and if successful, each action is passed a trigger object that contains information related to what event triggered the action to run. The trigger object is different for each type of trigger that can call an action and has a type object describing which type of trigger activated.

Types of triggers 

API endpoint trigger 

Condition that activates trigger

Executes when a corresponding mutation associated with an action is triggered through the API generated for your application.

Whenever the specific mutation for an action is called, the trigger then assesses permission through the access control. If allowed the action is run the data within your API is updated, and the resulting record or errors are returned by the API. These mutations can be invoked from the JavaScript client of your application or from a React app using the @gadgetinc/react hooks library, providing a convenient way to interact with and trigger actions through the API.

Output params sent to the action

a example API trigger
json
1{
2  "type": "api",
3  "mutationName": "updateWidget",
4  "rootAction": "update",
5  "rawParams": {
6    "id": "123",
7    "widget": {
8      "title": "New Widget Title",
9      "inventoryCount": 10
10    }
11  }
12}
  • type: will always be set to api.
  • mutationName: the string name of the mutation called in the API.
  • rootAction: the API identifier of the action triggered by the mutation.
  • rawParams: the params passed to this API call.

Scheduler trigger 

Is used for automating tasks that need to occur at regular intervals, such as data fetching, reporting, or maintenance tasks within your Gadget application.

  1. Scheduling: You can set up the scheduler trigger to run your action at specific times, such as every hour or every Thursday at midnight. You can add multiple entries to the schedule to have it run at different times or on different days.

  2. Execution: When the time arrives for a scheduled action to run, the scheduler trigger initiates the execution of the associated Global Action.

  3. Overlapping Executions: If a scheduled action takes longer to run than the interval between executions, subsequent executions that overlap will be ignored. For example, if an action is scheduled to run every minute but takes 3.5 minutes to complete, the executions that were scheduled during that 3.5-minute window will be skipped.

  4. Cron Expressions: The scheduler trigger supports cron expressions for scheduling. You can use cron expressions to define more complex schedules, and multiple cron expressions will be combined to create the overall schedule.

Condition that activates trigger

Executes at a set pre-configured time, similar to a cron job.

Output params sent to the action

json
{
  "type": "scheduler"
}

Shopify webhook trigger 

Condition that activates trigger

Executes when Shopify sends a webhook to your Gadget application.

  1. Gadget receives the webhook and performs an authenticity verification process to ensure it's from a trusted source.
  2. The trigger then initiates the corresponding action associated with the Shopify webhook event, such as create, update, or delete.

Shopify webhook triggers can also be added to global actions. For more information on how to use webhook triggers in model vs global actions check out the guide here.

Output params sent to the action

json
1// An example Shopify Webhook trigger
2{
3  "type": "shopify_webhook",
4  "topic": "products/update",
5  "payload": {
6    "id": 788032119674292900,
7    "title": "Example T-Shirt",
8    "body_html": "An example T-Shirt",
9    "vendor": "Acme",
10    "product_type": "Shirts",
11    "created_at": null,
12    "handle": "example-t-shirt"
13    // ... etc matching Shopify's format exactly
14  },
15  "shopId": "shop123",
16  "retries": 0
17}
  • type: will always be set to shopify_webhook
  • topic: the string representing the topic of the incoming webhook from Shopify, like products/update or orders/create
  • payload: the raw incoming payload from Shopify, which includes all the data sent by the webhook unchanged
  • shopId: the identifier for the Shopify store that received the webhook
  • retries: the number of times this webhook has been retried

The complete payload of the webhook received is accessible within the trigger object that is passed to your action code.

Shopify sync trigger 

It is designed to ensure that your Gadget application's data remains in sync with the Shopify store it's connected to. The sync trigger operates in 2 main scenarios:

  1. Manual Sync: A manual sync can be initiated by the user through the Gadget interface or via an API call.

  2. API-Triggered Sync: This type of sync can be initiated programmatically via the GraphQL API, JS clients, or within the actions code of your Gadget application. It's often used after a shop installation or when you want to sync data within a specified date range.1.

Condition that activates trigger

Executes as part of the Shopify sync model's actions.

Output params sent to the action

An example Shopify Sync trigger
json
1{
2  "type": "shopify_sync",
3  "shopId": "123456",
4  "apiVersion": "2023-01",
5  "shopifyScopes": ["read_products", "write_products"],
6  "syncId": "1",
7  "syncSince": null,
8  "models": ["shopifyShop", "shopifyProduct"],
9  "force": false,
10  "startReason": undefined // will be "scheduled" if Action ran via daily sync
11}
  • type: Will always be set to shopify_sync
  • shopId: The identifier of the Shopify shop being synced
  • apiVersion: The version of the Shopify API being used for the sync
  • shopifyScopes: The available OAuth scopes of the Shopify shop being synced
  • syncId: The identifier of the sync record tracking the state of this sync (optional, only available if set)
  • syncSince: The specified date range of this sync (optional, only set if specified when the sync was started)
  • models: The list of model API identifiers that this sync will work on
  • force: Indicates if this sync is being run in 'force' mode, which will always run actions even if the 'updated_at' timestamps match between Gadget and Shopify
  • startReason: The string describing the reason why this sync was started (optional, only set if specified when the sync began)

Google OAuth Sign Up trigger 

This trigger is part of the authentication process that integrates Google as an OAuth provider in your application. The entire profile payload from Google plus the additional data from the user model to the action to receive the necessary information from the user's Google profile.

Condition that activates trigger

Executes when a new user signs up using Google OAuth.

Output params sent to the action

json
1// An example Google OAuth sign up trigger
2{
3  "type": "Google-sign-up",
4  "id": 1,
5  "createdAt": "08/15/23",
6  "updatedAt": "08/15/23",
7  "googleProfileId": "115587437536377874490",
8  "resetPasswordToken": null,
9  "emailVerificationTokenExpiration": true,
10  "password": null,
11  "firstName": "Gizmo",
12  "lastSignedIn": "08/15/23",
13  "resetPasswordTokenExpiration": null,
14  "email": "[email protected]",
15  "emailVerificationToken": null,
16  "roles": "signed-in",
17  "emailVerified": true,
18  "googleImageUrl": "https://lh3.googleusercontent.com/a",
19  "lastName": "App"
20}
  • type: Specifies the type of trigger, in this case, "Google-sign-up".
  • id: A unique identifier for the user model.
  • createdAt: The date and time when the account was created.
  • updatedAt: The date and time when the account was last updated.
  • googleProfileId: The unique identifier for the Google profile associated with this account.
  • resetPasswordToken: A token used for resetting the password, currently set to null.
  • emailVerificationTokenExpiration: Indicates whether the email verification token has expired.
  • password: The password for the account, if there is one set.
  • firstName: The first name of the user.
  • lastSignedIn: The date and time when the user last signed in.
  • resetPasswordTokenExpiration: The expiration date and time of the reset password token, currently null.
  • email: The email address of the user.
  • emailVerificationToken: A token used for verifying the email, currently null.
  • roles: The roles assigned to the user, in this case, "signed-in".
  • emailVerified: A boolean indicating whether the user's email has been verified.
  • googleImageUrl: The URL of the user's Google profile image.
  • lastName: The last name of the user.

Default email/password authentication triggers 

Every Gadget web app template by default comes with several out-of-the-box authentication triggers associated with the corresponding authentication actions.

The following authentication triggers although named differently all have the same behavior of the API endpoint trigger.

  • Sign up
  • Sign in
  • Verify email
  • Reset password
  • Send reset password
  • Send verify email
  • Change password