Webhooks

Webhooks are a crucial part of API development, allowing for real-time reactions to various events across different systems, such as when a Stripe Payment is made, or when a GitHub issue is created.

​

Advantages of using Trigger.dev for webhooks

Webhooks can be difficult to work with, especially when developing locally. We make them far easier to use with our integrations.

• You don’t need to register/unregister for webhooks, we do it for you
• They work locally during development without needing to use tunnels (e.g. Ngrok)
• We receive the webhook, then keep trying to send it to you until you receive it. If your server goes down, no problem.

​

Usage

There are two ways to use webhooks with Trigger.dev:

1. Use one of our built-in integrations, such as GitHub. We’ll take care of registering the webhook for you.
2. Use our webhookEvent function to create a webhook subscription and you’ll register the webhook yourself.

​

Webhook integrations

We currently have built in integrations for the following webhooks:

• GitHub

Please join our discord community and let us know which integration you’d like us to add.

We’ve documented all the support webhooks for each integration in the sidebar, for example the GitHub newStarEvent webhook:

import * as github from "@trigger.dev/github";

new Trigger({
  id: "demo",
  on: github.events.newStarEvent({
    repo: "triggerdotdev/trigger.dev",
  }),
  run: async (event, ctx) => {},
}).listen();

Once you’ve connected to Trigger.dev, and authorized your GitHub account, we’ll go ahead and register the webhook in the repository you’ve specified and start triggering your Trigger.run function when new stars roll in.

​

Manual Webhooks

If we haven’t built out the integration you need, you can use our webhookEvent function to create a webhook subscription. You’ll need to register the webhook yourself, but we’ll take care of the rest. Here’s an example for triggering events when a new booking happens in Cal.com:

import { Trigger, webhookEvent } from "@trigger.dev/sdk";
import { z } from "zod";

new Trigger({
  id: "caldotcom-to-slack",
  name: "Cal.com To Slack",
  on: webhookEvent({
    service: "cal.com",
    eventName: "BOOKING_CREATED",
    filter: {
      triggerEvent: ["BOOKING_CREATED"],
    },
    schema: z.any(),
    verifyPayload: {
      enabled: true,
      header: "X-Cal-Signature-256",
    },
  }),
  run: async (event, ctx) => {},
}).listen();

For more information on the various options for webhookEvent, see the webhookEvent reference.

Once you connect to Trigger.dev, we will display the URL and (optionally) the secret you need to register with the webhook provider on the workflow overview page:

Copy the URL and secret, and register the webhook with the provider (in this case, Cal.com). Once you’ve done that, we’ll start triggering your Trigger.run function when the webhook fires.

​

Examples

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

new Trigger({
  id: "escalate-critical-issues",
  name: "Posts to Slack when GitHub Issue created or modified",
  apiKey: "<my_api_key>",
  //this is the webhook subscription
  on: github.events.issueEvent({
    repo: "my-github-org/my-github-repo",
  }),
  //this function is run when the webhook fires
  run: async (event, ctx) => {
    if (event.action === "labeled") {
      await ctx.logger.info(
        `The issue ${event.issue.title} was labeled ${event.label.name}`
      );

      if (event.label.name === "critical") {
        await slack.postMessage("send-to-slack", {
          channel: "serious-issues",
          text: `Critical issue: ${event.issue.title} was labeled ${event.label.name}`,
        });
      }
    }

    return event;
  },
}).listen();