Triggers (also called sources) are different from actions - they are not invoked directly by end users, but rather by events that happen on a third-party service. For example, the “New File” source for Google Drive will be triggered every time a new file is created in a specific folder in Google Drive, then will emit an event for you to consume.

All this means is that actions can be invoked manually on demand, while sources are instead deployed and run automatically when the event they are listening for occurs.

​
Categories of triggers

These are 2 categories of triggers you can deploy on behalf of your end users:

Refer to the full Connect API reference to list, retrieve, delete, and manage triggers for your user.

​
App-based event sources

​
Handling test events

  • Many event sources attempt to retrieve a small set of historical events on deploy to provide visibility into the event shape for end users and developers
  • Exposing real test events make it easier to consume the event in downstream systems without requiring users to trigger real events (more info)
  • However, this results in emitting those events to the listening webhook immediately, which may not always be ideal, depending on your use case
  • If you’d like to avoid emitting historical events, you can deploy a trigger without defining a webhook_url, then update the listening webhooks for the deployed trigger after roughly a minute

​
Native triggers

  • You can also deploy native triggers, which don’t require any authentication from your end users, so you should skip the account connection process when configuring these triggers
  • Because these triggers don’t use a connected account from your end users, APIs to deploy and manage them are slightly different (see below)

​
Deploying a source

Because sources are exercised by events that happen on a third-party service, their semantics are different from actions. Once a source is configured, it must be deployed to start listening for events. When deploying a source, you can define either a webhook URL or a Pipedream workflow ID to consume those events.

Deploying a source is done by sending a payload similar to the one used for running an action, with the addition of the webhook URL or workflow ID. Using the New Issue (Instant) source for Gitlab as an example, the payload would look something like this:

{
  "external_user_id": "abc-123",
  "id": "gitlab-new-issue",
  "prop_name": "http",
  "configured_props": {
    "gitlab": {
      "authProvisionId": "apn_kVh9AoD"
    },
    "projectId": 45672541
  },
  "webhook_url": "https://events.example.com/gitlab-new-issue"
}

Deploy a source for your users:

const { data: deployedTrigger } = await pd.deployTrigger({
  externalUserId: "abc-123",
  triggerId: "gitlab-new-issue",
  configuredProps: {
    gitlab: {
      authProvisionId: "apn_kVh9AoD",
    },
    projectId: 45672541,
  },
  webhookUrl: "https://events.example.com/gitlab-new-issue"
});
 
const {
  id: triggerId,      // The unique ID of the deployed trigger
  name: triggerName,  // The name of the deployed trigger
  owner_id: userId,   // The unique ID in Pipedream of your user
} = deployedTrigger;
 
// Parse and return the data you need

If the source deployment succeeds, the response will contain the information regarding the state of the source, including all the component’s props metadata, as well as their values. It will also contain its name, creation date, owner, and most importantly its unique ID, which can be used to manage the source in the future (e.g. delete it). The response for the request above would look like this:

{
  "data": {
    "id": "dc_dAuGmW7",
    "owner_id": "exu_oedidz",
    "component_id": "sc_3vijzQr",
    "configurable_props": [
      {
        "name": "gitlab",
        "type": "app",
        "app": "gitlab"
      },
      {
        "name": "db",
        "type": "$.service.db"
      },
      {
        "name": "http",
        "type": "$.interface.http",
        "customResponse": true
      },
      {
        "name": "projectId",
        "type": "integer",
        "label": "Project ID",
        "description": "The project ID, as displayed in the main project page",
        "remoteOptions": true
      }
    ],
    "configured_props": {
      "gitlab": {
        "authProvisionId": "apn_kVh9AoD"
      },
      "db": {
        "type": "$.service.db"
      },
      "http": {
        "endpoint_url": "https://xxxxxxxxxx.m.pipedream.net"
      },
      "projectId": 45672541
    },
    "active": true,
    "created_at": 1734028283,
    "updated_at": 1734028283,
    "name": "My first project - exu_oedidz",
    "name_slug": "my-first-project---exu-oedidz-2"
  }
}

In the example above, the source ID is dc_dAuGmW7, which can be used to delete, retrieve, or update the source in the future.

Refer to the full Connect API reference for questions and additional examples.

​
Native trigger examples

​
HTTP Webhook

Generate a unique HTTP webhook URL for your end users to configure in any other upstream service.

const { data: deployedTrigger } = await pd.deployTrigger({
  externalUserId: "abc-123",
  triggerId: "http-new-requests",
  webhookUrl: "https://events.example.com/http-new-requests"
});
 
const {
  id: triggerId,              // The unique ID of the deployed trigger
  endpoint_url: endpointUrl,  // The endpoint URL to return to the user
} = deployedTrigger;
 
// Parse and return the data you need

​
Example response

{
  "id": "hi_zbGHMx",
  "key": "xxxxxxxxxx",
  "endpoint_url": "http://xxxxxxxxxx.m.pipedream.net",
  "custom_response": true,
  "created_at": 1744508049,
  "updated_at": 1744508049
}

​
Schedule

Deploy a timer to act as a cron job that will emit an event on a custom schedule you or your users define.

​
Configured props

cron (object)

When defining schedules, you can pass one of the following:

  • intervalSeconds: Define the frequency in seconds
  • cron: Define a custom cron schedule and optionally define the timezone. For example:
"cron": {
  "cron": "0 * * * *",
  "timezone": "America/Los_Angeles" // optional, defaults to UTC
}

const { data: deployedTrigger } = await pd.deployTrigger({
  externalUserId: "abc-123",
  triggerId: "schedule-custom-interval",
  configuredProps: {
    "cron": {
      "intervalSeconds": 900
    }
  },
  webhookUrl: "https://events.example.com/schedule-custom-interval"
});
 
const {
  id: triggerId,  // The unique ID of the deployed trigger
} = deployedTrigger;
 
// Parse and return the data you need

​
Example response

{
  "id": "ti_aqGTJ2",
  "interval_seconds": 900,
  "cron": null,
  "timezone": "UTC",
  "schedule_changed_at": 1744508391,
  "created_at": 1744508391,
  "updated_at": 1744508391
}

​
New emails received

Generate a unique email address for your customers to emit events to

const { data: deployedTrigger } = await pd.deployTrigger({
  externalUserId: "abc-123",
  triggerId: "email-new-email",
  webhookUrl: "https://events.example.com/email-new-email"
});
 
const {
  id: triggerId,              // The unique ID of the deployed trigger
  email_address: emailAddress,  // The unique email address to return to the user
} = deployedTrigger;
 
// Parse and return the data you need

​
Example response

{
  "id": "ei_QaJTb0",
  "email_address": "xxxxxxxxxx@upload.pipedream.net",
  "created_at": 1744499847,
  "updated_at": 1744499847
}