Integrations: Overview

How to use Trigger.dev Integrations

You can use any API in your Jobs by using existing Node.js SDKs or HTTP requests. Integrations just make it much easier especially when you want to use OAuth. And you get great logging.

Integrations allow you to quickly use APIs, including webhooks and Tasks.

Authentication

There are two ways to authenticate Integrations, OAuth and API Keys/Access Tokens.

API Keys/Access Tokens

Use API Keys or Access Tokens to connect an Integration

OAuth

Use OAuth to connect an Integration for your team or your users

Bring-your-own Auth

Use our integrations with your user’s auth credentials, using Clerk.com, Nango.dev, or rolling your own with our custom auth resolvers

Using for Jobs & Tasks

You must pass Integrations into your Job to run integration tasks. Passed in Integrations will be available on the io object in the run() function with the same name as the key. For example:

client.defineJob({
  //... other options
  integrations: {
    slack,
    gh: github,
  },
  run: async (payload, io, ctx) => {
    //slack is available on io.slack
    io.slack.postMessage(...);
    //github is available on io.gh
    io.gh.addIssueLabels(...);
  }
});

Both the postMessage and addIssueLabels functions above are implemented as an “Authenticated Task” that is defined inside the Integration, where the first argument is always the task key and the second argument is the parameters for the task. For example, here is how you would call the postMessage function above:

client.defineJob({
  // ...
  integrations: {
    slack,
  },
  run: async (payload, io, ctx) => {
    const response = await io.slack.postMessage("✋", {
      channel: "C04GWUTDC3W",
      text: "My first Slack message",
    });
  },
});

The above code will create a Task that will use the authentication configured for the specified Slack integration.

If the integration does not support a specific task function that you want to use, you can use the runTask function to get access to the authenticated client.

For example, the Slack integration doesn’t expose an Authenticated Task function for deleting a message, but you can use the chat.delete function provided by the @slack/web-api package directly:

client.defineJob({
  // ...
  integrations: {
    slack,
  },
  run: async (payload, io, ctx) => {
    const response = await io.slack.postMessage("✋", {
      channel: "C04GWUTDC3W",
      text: "My first Slack message",
    });

    await io.wait("⏰", 24 * 60 * 60 * 1000); // wait 24 hours

    await io.slack.runTask("delete", async (slack) => {
      return slack.chat.delete({
        channel: "C04GWUTDC3W",
        ts: response.ts!,
      });
    });
  },
});

You can optionally pass a third parameter to runTask to specify the task parameters:

await io.slack.runTask(
  "delete",
  async (slack) => {
    return slack.chat.delete({
      channel: "C04GWUTDC3W",
      ts: response.ts!,
    });
  },
  {
    name: "Delete message",
    properties: [{ label: "Message", text: response.ts }],
  }
);

View the runTask reference for more information.

Using outside of Jobs

If you want to use integrations that support “local auth” only (e.g. API keys, like Stripe and Supabase) outside of a Job you can use the .native property on the integration to get direct access to the client. For example:

stripe.ts

import { Stripe } from "@trigger.dev/stripe";

const stripe = new Stripe({
  id: "stripe",
  apiKey: process.env.STRIPE_SECRET_KEY!,
});

async function createCustomer() {
  await stripe.native.customers.create({
    // ... customer attributes go here
  });
}

Using for Triggers

Some integrations provide triggers that you can use to start a Job. For example, the GitHub integration provides a push trigger that will start a Job when a new commit is pushed to a repository:

import { Github, events } from "@trigger.dev/github";

const github = new Github({
  id: "github",
  token: process.env.GITHUB_TOKEN!,
});

client.defineJob({
  id: "github-integration-on-push",
  name: "GitHub Integration - On Push",
  version: "0.1.0",
  trigger: github.triggers.repo({
    event: events.onPush,
    owner: "triggerdotdev",
    repo: "trigger.dev",
  }),
  run: async (payload, io, ctx) => {
    // do something on push
  },
});

Behind the scenes, our @trigger.dev/github integration will create a webhook on your repository that will call our API when a new push event is received. We will then start your Job with the payload from the push event.

If you are just using an integration to trigger a job but not using authenticated tasks inside the job run, there is no need to pass the integration in the job integrations option.