---
title: Plugin Trigger
---

## Introduction

<Info>
    Triggers are available for workflow applications only.
</Info>

A plugin trigger automatically initiates your workflow when a specific event occurs in an external system. All you need to do is subscribe to these events through a trigger plugin and add the corresponding plugin trigger to your workflow.

For example, suppose you have installed a GitHub trigger plugin. It provides a list of GitHub events you can subscribe to, including `Pull Request`, `Push`, and `Issue`. If you subscribe to the `Pull Request` event and add the `Pull Request` plugin trigger to your workflow, it will automatically run whenever someone opens a pull request in the specified repository.

## Add and Configure a Plugin Trigger

1. On the workflow canvas, right-click and select **Add Node** > **Start**, then choose from the available plugin triggers or search for more in [Dify Marketplace](https://marketplace.dify.ai/?language=en-US&category=trigger).

    <Tip>
        - If there's no suitable trigger plugin for your target external system, you can [request one from the community](https://github.com/langgenius/dify-plugins/issues/new?template=plugin_request.yaml), [develop one yourself](/plugin-dev-en/0222-trigger-plugin), or use a [webhook trigger](/en/guides/workflow/node/webhook-trigger) instead.

        - A workflow can have multiple plugin triggers running in parallel. When the parallel branches contain identical consecutive nodes, you can add a [Variable Aggregator](/en/guides/workflow/node/variable-aggregator) node to merge the branches before the common section, without duplicating the same nodes across each branch.
    </Tip>

2. Select an existing subscription or [create a new one](#create-a-new-subscription).

    <Tip>
        View how many workflows are using a specific subscription from the plugin's details panel under **Plugins**.
    </Tip>

3. Configure any other required settings.

<Info>
    The output variables of a plugin trigger are defined by its trigger plugin and cannot be modified.
</Info>

## Create a New Subscription

<Note>
    A subscription cannot be modified once created. To make changes, delete the existing one and create a new subscription. 
</Note>

<Info>
    A trigger plugin supports creating up to 10 subscriptions per workspace.
</Info>

Each subscription is built on a webhook. When you create a subscription, you're essentially setting up a webhook that listens for events from an external system. 

<Accordion title="What is a webhook?">

    A webhook allows one system to automatically send real-time data to another. When a certain event occurs, the source system packages the event details into an HTTP request and sends it to a designated URL provided by the destination system.

</Accordion>

Dify supports the following two methods for creating subscriptions (webhooks), but the options available in each plugin depend on how that plugin was designed.

- **Automatic Creation**: You select the events you want to subscribe to, and Dify automatically creates the corresponding webhook in the external system. This requires prior authorization via **OAuth** or **API keys** so Dify can handle the webhook setup on your behalf.

- **Manual Creation**: You create the webhook yourself using the webhook callback URL provided by Dify. No authorization is needed.

<img src="/images/create_subscription_method.png" alt="Ways to Create Subscriptions" width="563" />

<Tip>
    It's recommended to select all available events when creating a subscription.
    
    A plugin trigger works only when its corresponding event is included in the linked subscription. Selecting all available events ensures that any plugin trigger you add to the workflow later can use the same subscription, without creating another one.
</Tip>

<Tabs>
    <Tab title="Create with OAuth (Automatic)">

    On Dify Cloud, many popular trigger plugins are pre-configured with default OAuth clients so you can authorize Dify with a single click. 
    
    For self-hosted deployments, only the custom OAuth client option is available, meaning that you need to create the OAuth application yourself in the external system.

        <Tabs>
            <Tab title="Default OAuth Client">

                1. Select **Create with OAuth** > **Default** > **Save and Authorize**.

                    <Info>
                        **Save** means the selected option is set as the default OAuth method for future subscriptions.

                        To switch methods later, click the **OAuth Client Settings** icon.

                        <img src="/images/oauth_client_settings_icon.png" alt="OAuth Client Settings Icon" width="300" />

                    </Info>

                2. On the external system's authorization page that pops up, click **Next** to grant Dify access.

                3. Specify the subscription name, select the events you want to subscribe to, and configure any other required settings.

                    <Tip>
                        We recommend selecting all available events.
                    </Tip>

                4. Click **Create**.

            </Tab>

            <Tab title="Custom OAuth Client">

            1. Select **Create with OAuth** > **Custom**.

            2. In the external system, create an OAuth application using the callback URL provided by Dify.

            3. Back in Dify, enter the client ID and client secret of the newly created OAuth application, then click **Save and Authorize**.

                <Info>
                    Once saved, the same client credentials can be reused for future subscriptions.
                </Info>

            4. Specify the subscription name, select the events you want to subscribe to, and configure any other required settings.
                <Tip>
                    We recommend selecting all available events.
                </Tip>

            5. Click **Create**.

            </Tab>

        </Tabs>

        <Info>
            The displayed **Callback URL** is used internally by Dify to create the webhook in the external system on your behalf, so you don't need to take any action with this URL.

            For self-hosted deployments, you can change the URL's base prefix via the `TRIGGER_URL` environment variable. Ensure it points to a public domain or IP address accessible to external systems.
        </Info>
    </Tab>

    <Tab title="Create with API Key (Automatic)">

    1. Select **Create with API Key**.

    2. Enter the required authentication information, then click **Verify**.

    3. Specify the subscription name, select the events you want to subscribe to, and configure any other required settings.

        <Tip>
            We recommend selecting all available events.
        </Tip>

    4. Click **Create**.

    <Info>
        The displayed **Callback URL** is used internally by Dify to create the webhook in the external system on your behalf, so you don't need to take any action with this URL.

        For self-hosted deployments, you can change the URL's base prefix via the `TRIGGER_URL` environment variable. Ensure it points to a public domain or IP address accessible to external systems.
    </Info>
    
    </Tab>

    <Tab title="Paste URL to Create a New Subscription (Manual)">

    1. Select **Paste URL to create a new subscription**.

    2. Specify the subscription name and use the provided callback URL to manually create a webhook in the external system. 

        <Info>
            For self-hosted deployments, you can change the callback URL's base prefix via the `TRIGGER_URL` environment variable.
    
            Ensure the prefix points to a public domain or IP address accessible to external systems.
        </Info>

    3. (Optional) Test the created webhook.

        <Info>
            Most external systems automatically test a new webhook by sending a ping request to Dify upon creation.
        </Info>
    
        1. Trigger a subscribed event so the external system sends an HTTP request to the callback URL.

        2. Return to the **Manual Setup** page and check the **Request Logs** section at the bottom. If the webhook works properly, you'll see the received request and Dify's response.

            <img src="/images/plugin_trigger_manual_setup_request_logs.png" alt="Request Logs" width="563" />

    4. Click **Create**.

    </Tab>

</Tabs>

## Test a Plugin Trigger

To test an unpublished plugin trigger, you must first click **Run this step** or test-run the entire workflow. This puts the trigger into a listening state so that it can monitor external events. Otherwise, the trigger will not capture subscribed events even when they occur.

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

---

[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/guides/workflow/node/plugin-trigger.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)

