> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Add a Custom Trigger

## Article: Add a Custom Trigger

## Article Link: https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/automations/add-a-custom-trigger.md

## Article Content:

# Add a Custom Trigger

[Custom triggers](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/automations/about-custom-triggers.md) give you the ability to run an automation from anywhere in your site code. This article explains how to create a custom trigger and use the [Custom Trigger API](https://dev.wix.com/docs/sdk/backend-modules/automations/triggers/custom-trigger/introduction.md) to run your automation.

## Step 1 | Install the Automations SDK package

**If you're working in the editor or Wix IDE:**

1. **Wix Studio:** In the code panel on the left of the site editor, go to **Code** ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXdfXqgbsvw2g99hQiSntBzAxxAORy6WRHLsf22RvMTIBfk1WBJpVGsF07YNTJQHDF9-15t_41vpyMexYPtsznlrxCeh3QlHt5-UWKIVXOBHAX2MLH7hiCaLj_u2qwNYg3cEHtj9tg?key=TRmYtOkLPB3ZtFBvYpkeO1-L) > **Packages & Apps**.

    **Wix Editor**: Make sure **Dev Mode** is [enabled](https://dev.wix.com/docs/velo/articles/getting-started/getting-oriented.md#enabling-velo). Then, in the code sidebar on the left, go to **Packages & Apps** ![](https://lh7-rt.googleusercontent.com/docsz/AD_4nXdqeMv-MqXNE-PI2_HaUzKj51PV2-k6QjjLxa5j1FbLoSO7QHpbiPee8EGecy4q0KLvUoDm5UUXvHqlyBBuyLLai7D5TalnH951XahLmXlpaoQK48QWMi3myS7yw01StZW0nj1Bag?key=TRmYtOkLPB3ZtFBvYpkeO1-L).
    
1. Under **npm**, click **+ Install packages from npm**.
1. Search for and install the `@wix/automations` package.

    ![Install the wix/automations package](https://wixmp-833713b177cebf373f611808.wixmp.com/images/1b8b13984ebc10f4447d657269922f3a.png)

1. Repeat these steps to install the `@wix/essentials` package.

**If you're working in your local IDE:**

1. Install the necessary packages on your command line:

    ```bash
    npm install @wix/automations
    npm install @wix/essentials
    ```

Now that you’ve installed the `@wix/automations` package, you’re able to use the Custom Trigger API in your site code. Before you write any code, however, you need to create an automation that uses the **Velo code trigger**.

## Step 2 | Create an automation with the Velo code trigger

To create a new automation:

1. Go to the [Automations](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site\&title=Select%20a%20Site\&autoSelectOnSingleSite=true\&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Ftriggers) page in your site dashboard.
1. Click **+ New Automation** > **+ Start from Scratch** to open the builder. Give your new automation a title.
1. In the left menu, from the list of available triggers, select **Velo code trigger**.

    Once you select the trigger, the left panel displays instructions on how to work with the trigger, as well as the trigger ID and the payload. The bottom part of the panel also displays sample code that you can copy.

### Define the payload structure (optional)

You have the option to define the trigger payload schema by inputting sample data. Wix provides you with default sample data, which you can choose to keep or replace with your own data.

To define a payload schema for the trigger:

1. In the **Velo code trigger** panel, click **{..} Set Payload Data Structure**.

    ![Set the payload data structure](https://wixmp-833713b177cebf373f611808.wixmp.com/images/e90961c6dcabe759d298c58a059c39e6.png)

1. Edit the displayed JSON data as necessary, then click **Preview Structure >**. A preview of your payload schema opens.

    ![Payload structure preview](https://wixmp-833713b177cebf373f611808.wixmp.com/images/ae58f83cfc42debf8fefe5386d0cb88d.png)

1. Optionally, click **Mark Contact ID** to mark one of the UUIDs as a [contact ID](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/automations/about-custom-triggers.md#contact-data-in-the-payload-schema).

    ![Mark a UUID field as a contact ID](https://wixmp-833713b177cebf373f611808.wixmp.com/images/472c6319a914b597ceb0bf6e91f3296f.png)

    Only fields in proper UUID format appear on the list. You may only select one field to be a contact ID. Click **Save** to exit the **Mark Contact ID** modal.

1. When you’re satisfied with your payload schema structure, click **Save Structure**. You can return to edit the structure in the builder at any time.

### Copy code and complete automation setup

Whether you define a payload or not, Wix provides you with the trigger ID, which you need to run your automation, as well as some example code.

1. Copy the trigger ID to use for later in your site code. At the bottom of the trigger configuration panel, click **Show code >**.

    ![Show the sample code to use Run Trigger](https://wixmp-833713b177cebf373f611808.wixmp.com/images/c524894dfc1c8cff746dcc7f0c09b7b4.png)

    The trigger setup provides you with some sample code. Copy this code for use as a starting point in your own code.
1. Click **Apply** to save your trigger setup.
1. Select and configure at least one action as part of your automation, then activate the automation.

Now that you’ve configured your automation, you can write the code to run it for any event.

## Step 3 | Implement Run Trigger in site code

In order to implement Run Trigger, you need to define a [web method](https://dev.wix.com/docs/velo/apis/wix-web-module/introduction.md) in the backend that calls the method. Then you can export that web method to other code files for use.

1. If you’re working in the editor, create a new [web module](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/backend-code/web-modules/about-web-modules.md) in the **Backend & Public** > **Backend** section of the code panel. If you’re working in the Wix IDE or locally, add the file under `src/backend`.

1. In the web module, paste the code you copied from the automation setup, so that your file looks like this:

    ```javascript
    import { customTrigger} from "@wix/automations";
    import { auth } from '@wix/essentials';
    import { Permissions, webMethod } from "wix-web-module";

    export const runTrigger = webMethod(
      Permissions.Anyone,
      async (payload) => {
        const triggerMethod = auth.elevate(automations.runTrigger);

        // Your code here
        await triggerMethod({
          triggerId: 'triggerId',
          payload,
        });
      }
    );
    ```

    Let’s break down the important lines in this code:

    **Lines 1-3**. Import necessary packages, including the `@wix/automations` package that contains the Run Trigger functionality, and the `@wix/essentials` package that provides auth functionality.
    
    **Line 5**. Create the web method to export to the frontend.
    
    **Line 8**. [Elevate](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md#elevate) Run Trigger so it runs with the correct permissions.
    
    **Lines 11-14**. Call the elevated method. In place of `triggerId`, enter the trigger ID you copied from your automation. If you defined a payload schema for your trigger, pass the `payload` argument as well.

1. Export your web method to another file, such as the frontend code for a site page. Add this line to the top of the file you want to import the method into:

    ```javascript
    import { runTrigger } from 'backend/triggers.web';
    ```

1. Call the method in the file code where necessary. To give a simple example, let’s say you add a [button](https://dev.wix.com/docs/velo/velo-only-apis/$w/button/introduction.md) element to your site page, and you want to run the automation every time a visitor clicks that button. You can then simply call Run Trigger in that button’s `onClick()` handler:

    ```javascript
    $w('#myButton').onClick(async () => {
        runTrigger();
    })
    ```

    If you defined a payload schema for your trigger, you can pass a payload object to Run Trigger. All payload fields are optional, but any fields you include in the payload should match the keys and types defined in the schema.
1. To test your code, either publish your site or [create a test site](https://support.wix.com/en/article/test-sites-creating-a-test-site). Your backend code may not work in Preview mode.

## See also

- [About Custom Triggers](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/automations/about-custom-triggers.md)
- [Custom Trigger SDK](https://dev.wix.com/docs/sdk/backend-modules/automations/triggers/custom-trigger/introduction.md)