Triggers

Triggers define the type of event that runs your workflow. Workflows execute on every trigger event.

For example, HTTP triggers expose a URL where you can send any HTTP requests. We'll run your workflow on each request. The Cron Scheduler trigger runs your workflow on a schedule.

Today, we support HTTP, Cron Scheduler, and email triggers. In the future we plan to support SQL, AMQP, and more. If there's a trigger you'd like supported, please let us know.

HTTP

When you select the HTTP trigger, we create a URL endpoint specific to your workflow.

You can send any HTTP requests to this endpoint, from anywhere on the web. You can configure the endpoint as the destination URL for a webhook or send HTTP traffic from your application - we'll accept any valid HTTP request.

Accessing HTTP request data

You can access properties of the HTTP request, like the method, payload, headers, and more, in the event object, accessible in any code or action step.

Valid Requests

You can send a request to your endpoint using any valid HTTP method: GET, POST, HEAD, and more.

We default to generating HTTPS URLs in the UI, but will accept HTTP requests against the same endpoint URL.

You can send data to any path on this host, with any query string parameters. You can access the full URL in the event object if you'd like to write code that interprets requests with different URLs differently.

You can send data of any Media Type in the body of your request.

The primary limit we impose is on the size of the request body: we'll issue a 413 Payload Too Large status when the body exceeds our specified limit.

How Pipedream handles JSON payloads

JSON is the main data exchange format on the web today. Pipedream optimizes for the case where you've sent JSON as the source event to a workflow.

When you send JSON in the HTTP payload, or when JSON data is sent in the payload from a webhook provider, Pipedream converts that JSON to its equivalent JavaScript object. The trigger data can be referenced using either event or the steps object.

You can confirm this JSON -> JavaScript object conversion occurred by examining the event.inferred_body_type property. If this is JSON, we correctly recognized the payload as such, and converted event.body to an object accordingly.

In the Inspector, we present event.body cleanly, indenting nested properties, to make the payload easy to read. Since event.body is a JavaScript object, it's easy to reference and manipulate properties of the payload using dot-notation.

Cross-Origin HTTP Requests

We return the following headers on HTTP OPTIONS requests:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET,HEAD,PUT,PATCH,POST,DELETE

Thus, your endpoint will accept cross-origin HTTP requests from any domain, using any standard HTTP method.

HTTP Responses

By default, when you send a valid HTTP request to your endpoint URL, you should expect to receive a 200 OK status code with the following payload:

<p><b>Success!</b></p>
<p>To customize this response, check out our docs <a href="https://docs.pipedream.com/workflows/steps/triggers/#http-responses">here</a></p>

This is a convenient default for workflows. When you're processing HTTP requests, you often don't need to issue any special response to the client. We issue this default response so you don't have to write any code to do it yourself.

If you do need to issue a custom HTTP response from a workflow, you can use the $respond() function in a Code or Action step.

$respond() takes a single argument: an object with properties that specify the body, headers, and HTTP status code you'd like to respond with:

$respond({
  status: 200,
  headers: { "my-custom-header": "value" },
  body: { message: "My custom response" } // This can be any string, object, or Buffer
});

Additionally, for Pipedream to issue this response, one of the following must be sent in the HTTP request:

  • A pipedream_response=1 query string parameter, e.g. a request must be made to https://myendpoint.m.pipedream.net/?pipedream_response=1, or
  • An x-pipedream-response HTTP header with any value

If the HTTP request does not contain at least one of these signals, the $respond() code in your workflow will not run.

This workflow contains example code and a README articulating how to use $respond(), as well.

Errors

Occasionally, you may encounter errors when sending requests to your endpoint:

Request Entity Too Large

The endpoint will issue a 413 Payload Too Large status code when the body of your request exceeds 100kb.

In this case, the request will still appear in the inspector, with information on the error.

API key does not exist

Your API key is the host part of the endpoint, e.g. the eniqtww30717 in eniqtww30717.m.pipedream.net. If you attempt to send a request to an endpoint that does not exist, we'll return a 404 Not Found error.

We'll also issue a 404 response on workflows with an HTTP trigger that have been deactivated.

Too Many Requests

If you send too many requests to your HTTP source within a small period of time, we may issue a 429 Too Many Requests response. Review our limits to understand the conditions where you might be throttled.

You can also reach out to inquire about raising this rate limit.

If you control the application sending requests, you should implement a backoff strategy to temporarily slow the rate of events.

Webhook

A Webhook trigger is an alias for the HTTP trigger. They are equivalent in every way. You can trigger workflows on HTTP requests using either the HTTP or Webhook trigger.

Cron Scheduler

Pipedream allows you to run hosted cron jobs — any code run on a schedule — for free.

We call these cron jobs "workflows". Workflows are just scripts that run on a schedule.

You can write a cron job to:

Pipedream manages the servers where these cron jobs run, so you don't have to worry about setting up a server of your own or operating some service just to run code on a schedule. You write the workflow, we take care of the rest.

Choosing a cron trigger

To create a cron job, create a new workflow and search for the Cron Scheduler trigger:

Cron Scheduler source

By default, your cron job will be turned Off. To enable it, select either of the scheduling options:

  • Simple : run the job every N days, hours, minutes (e.g. every 1 day, every 3 hours).
  • Cron expression : schedule your job using a cron expression. For example, the expression 0 0 * * * will run the job every day at midnight. Cron expressions can be tied to any timezone.

Testing a cron job

If you're running a cron job once a day, you probably don't want to wait until the next day's run to test your new code. You can manually run the workflow associated with a cron job at any time by pressing the Send Test Event button.

Future executions of your cron job

You'll see the time your job is scheduled to run next under the Next Job section of the Inspector.

Job History

You'll see the history of job executions under the Job History section of the Inspector.

Clicking on a specific job shows the execution details for that job — all the logs and observability associated with that run of the workflow.

Trigger a notification to an external service (email, Slack, etc.)

You can send yourself a notification — for example, an email or a Slack message — at any point in a workflow by using the relevant Action or Destination.

If you'd like to email yourself when a job finishes successfully, you can use the Email Destination. You can send yourself a Slack message using the Slack Action, or trigger an HTTP request to an external service.

You can also write code to trigger any complex notification logic you'd like.

Rate Limit

When you're testing cron jobs, you may encounter Rate Limit Exceeded errors. Cron jobs can be tested no more than twice a minute. If you encounter this error, wait one minute and try again.

Troubleshooting your cron jobs

When you run a cron job, you may need to troubleshoot errors or other execution issues. Pipedream offers built-in, step-level logs that show you detailed execution information that should aid troubleshooting.

Any time a cron job runs, you'll see a new execution appear in the Inspector. This shows you when the cron job ran, how long it took to run, and any errors that might have occurred. Click on any of these lines in the Inspector to view the details for a given run.

Code steps show Logs below the step itself. Any time you run console.log() or other functions that print output, you should see the logs appear directly below the step where the code ran.

Actions and Destinations also show execution details relevant to the specific Action or Destination. For example, when you use the HTTP Destination to make an HTTP request, you'll see the HTTP request and response details tied to that Destination step:

Limitations

Cron jobs can be run at most once a minute. Any cron expression that specifies a higher frequency will be rejected.

Cron jobs can run for at most 30 seconds. If your workflow takes longer than 30 seconds to execute, you'll see a TIMEOUT error for that run, and will be able to review all logs up until the timeout occurred.

There are other limits that apply to all workflows on Pipedream — see our Limits docs for more information.

Email

When you select the Email trigger, we create an email address specific to your workflow. Any email sent to this address triggers your workflow.

Read more about the shape of the email trigger event.

Limitations

See the Email Trigger section of our Limits doc to learn more about the limits of the email trigger.

Don't see a trigger you need?

If you don't see a trigger you'd like us to support, please let us know.

Still have questions?

Please reach out if this doc didn't answer your question. We're happy to help!