Using integrations

We provide a number of integrations to make it easy to work with 3rd party APIs, both for triggering your workflows through webhooks and for making API calls from your workflows.

​

Webhooks

Webhooks allow you to trigger your workflows when an event happens in a 3rd party service. For example, you can trigger a workflow when a new GitHub issue is created, or when a user in your slack interacts with a message. Using our integrations for webhooks gives you the following advantages over using raw webhooks:

• When working locally, you don’t need to expose your local server to the internet over a tunnel like ngrok.
• We will automatically register the webhook with GitHub for you, and verify the payload signature.
• We provide a nicely typed event payload to your run function, so you don’t have to setup webhook payload types.
• If your server isn’t running, we will wait until it’s back online before attempting to run the workflow.
• It is very easy to test your workflow locally using our Test Run feature.

​

Using webhooks in your workflow

To use an integration webhook to trigger a workflow, you first need to install the corresponding integration package. For example, if we wanted to use the github.newStarEvent webhook, we would install the @trigger.dev/github package:

• npm

• pnpm

• yarn

npm install @trigger.dev/github

We’d then import it and pass it to the on option of the Trigger constructor:

import { Trigger } from "@trigger.dev/sdk";
import * as github from "@trigger.dev/github";

new Trigger({
  id: "new-github-star",
  name: "New GitHub Star",
  on: github.events.newStarEvent({
    repo: "triggerdotdev/trigger.dev",
  }),
  run: async (event, ctx) => {
    // Do something with the event here
  },
}).listen();

Different webhooks have different parameters, so make sure and check out the documentation for the specific webhook you are using. For example, the github.newStarEvent webhook has a repo parameter, which is the name of the GitHub repo that you want to listen for stars on.

​

Authenticating webhooks

When you create a workflow with a webhook trigger (like the GitHub example above), we will automatically register the webhook for you, but you first need to authenticate with the 3rd party service (in this case, GitHub). Using the example above, after running the workflow for the first time, you will see a message like this in your app.trigger.dev dashboard:

Clicking through to the Workflow overview page, you will be prompted to authenticate to GitHub so we can register the webhook on your behalf:

After authenticating, you will be redirected back to the Workflow overview page, and your workflow will be ready to go:

​

Testing webhooks

When you are developing a workflow with a webhook trigger, you can test it locally using our Test Run feature. This will allow you to trigger your workflow without having to set up a webhook on the 3rd party service (in this case, GitHub). Using the example above, you can test your workflow by clicking the “Test workflow” button in the Workflow Overview page, which will bring you to a test page with some mock data for the event:

Clicking on “Run test” will trigger your workflow and bring you to the Workflow Run page, where you can see the results of your workflow:

​

Triggering webhooks

Another way to test your workflow is to trigger it using a real webhook payload. This is useful if you want to test your workflow with real data from the 3rd party service (in this case, GitHub). The easiest way to do that is to actually perform the action that will trigger the webhook (in this case, starring the specified GitHub repo):

​

API calls (a.k.a. “actions”)

Actions allow you to make API calls from your workflows. For example, you can post a message to Slack, or create a new GitHub issue. Using our integrations for actions gives you the following advantages over using raw API calls:

• We automatically handle the OAuth flow for you, so you don’t have to worry about setting up a Slack app and dealing with credentials in your code (see Authentication for more details).
• We will automatically retry the request if the API returns an error or you are rate limited.
• We provide a nicely typed response object, so you don’t have to setup API response types.

Each action doesn’t necessarily map to 1 API call as well. For example, our slack.postMessage action does the following things:

• We let you pass the channelName parameter to the postMessage function, and we will automatically resolve it to the channel ID for you (which is required by the Slack API).
• We will automatically invite the bot to the channel if it isn’t already a member.

​

Using actions in your workflow

To use an action in your workflow, you first need to install the corresponding integration package. For example, if we wanted to use the slack.postMessage action, we would install the @trigger.dev/slack package:

• npm

• pnpm

• yarn

npm install @trigger.dev/slack

Now you can import the integration and use the action inside the run function of your workflow:

import { Trigger } from "@trigger.dev/sdk";
import * as github from "@trigger.dev/github";
import * as slack from "@trigger.dev/slack";

new Trigger({
  id: "new-github-star",
  name: "New GitHub Star",
  on: github.events.newStarEvent({
    repo: "triggerdotdev/trigger.dev",
  }),
  run: async (event, ctx) => {
    await slack.postMessage("new-github-star", {
      channelName: "github-stars",
      text: `New star on ${event.repo}!`,
    });
  },
}).listen();

You can also use actions outside of the Trigger.run function, allowing you to wrap them in helper functions:

import { Trigger } from "@trigger.dev/sdk";
import * as github from "@trigger.dev/github";
import * as slack from "@trigger.dev/slack";

new Trigger({
  id: "new-github-star",
  name: "New GitHub Star",
  on: github.events.newStarEvent({
    repo: "triggerdotdev/trigger.dev",
  }),
  run: async (event, ctx) => {
    await postMessageToSlack("new-github-star", `New star on ${event.repo}!`);
  },
}).listen();

async function postMessageToSlack(key: string, text: string) {
  return slack.postMessage(key, {
    channelName: "github-stars",
    text,
  });
}

​

Action outputs

Some actions will return an output value. For example, the slack.postMessage action will return the ts value of the message that was posted:

const output = await slack.postMessage("new-github-star", {
  channelName: "github-stars",
  text: `New star on ${event.repo}!`,
});

console.log(`The message ts is ${output.ts}`);

You can consult the documentation for each action to see what outputs it returns.

​

Action errors & retries

We will retry actions up to 10 times if we receive certain error codes from an API. For example, if the Slack API returns a 429 error code (indicating that we are being rate limited), we will automatically retry the request after a short delay. Here is the retry schedule we use (using the following formula: delay = 1.8 ^ (retry - 1) * 1000

If the API returns a non-retryable status code, such as most client errors (4xx), we will not retry the request and instead the action will fail and the workflow run will halt and be marked as errored:

​

Authenticating actions

To be able to perform the actions in our integration packages, you will need to provide authentication information for the corresponding integration, which we will use to make the API calls. Integrations usually require either an API Key (such as Resend.com) or an OAuth token (such as Slack).

For OAuth integrations, we will automatically handle the OAuth flow for you, so you don’t have to worry about setting up a Slack app and dealing with credentials in your code. We will prompt you to authenticate the integration when you first use it in your workflow, and we will store the credentials securely in our database.

For example, when using the slack.postMessage action, if you haven’t already added a Slack integration, we will pause the action and ask you to authenticate:

Clicking on “Connect to Slack” will open a modal where you can authenticate the integration:

Once authenticated, the action will resume and the message will be posted to Slack: