defineHttpEndpoint()

Defines an HTTP Endpoint

These are the docs for Trigger.dev v2 which will be deprecated on January 31st, 2025. You probably want the v3 docs.

An HTTP endpoint allows you to create an HTTP Trigger, which means you can trigger your Jobs from any webhooks.

example

const caldotcom = client.defineHttpEndpoint({
  //this should be unique inside your project
  id: "cal.com",
  //usually you'd use the domain name of the service
  source: "cal.com",
  //the icon is optional, it displays in the dashboard
  icon: "caldotcom",
  //this function is called when a webhook is received
  verify: async (request) => {
    //this is a useful helper function that can verify sha256 signatures
    //each API has a different header name
    return await verifyRequestSignature({
      request,
      //you can find the header name in the API's documentation
      headerName: "X-Cal-Signature-256",
      //you can find the secret in the Trigger.dev dashboard, on the HTTP endpoint page
      secret: process.env.CALDOTCOM_SECRET!,
      algorithm: "sha256",
    });
  },
});

Parameters

options · HTTPEndpointOptions · required

The options for the HTTP endpoint.

Hide options

id · string · required

Used to uniquely identify the HTTP Endpoint inside your Project.

source · string · required

Usually you would use the domain name of the service, e.g. cal.com.

icon · string

An optional icon name that’s displayed in the dashboard. Lots of company names are supported, e.g. github, twilio. You can also reference the name of any Tabler icon, e.g. brand-google-maps, brand-twitch.

title · string

An optional title, displayed in the dashboard.

examples · array

Used to provide example payloads that are accepted by the job.

This will be available in the dashboard and can be used to trigger test runs.

Show example object properties

id · string · required

The example’s ID.

name · string · required

The name that’s displayed in the dashboard.

payload · object · required

The payload that’s accepted by the job.

icon · string

The icon to use for this example in the dashboard.

properties · array

Properties that are displayed in the logs.

Each property has the following fields:

Show property fields

label · string · required

The label for the property.

text · string · required

The value of the property.

url · string

The URL to link to when the property is clicked.

verify · function · required

This is compulsory, and is used to verify that the received webhook is authentic. It’s a function that expects you to return a result object like:

//if it's valid
return { success: true }
//if it's invalid, reason is optional
return { success: false, reason: "No header" }

In 90% of cases, you’ll want to use the verifyRequestSignature helper function we provide.

respondWith · object

This optional object allows you to immediately Respond to a Request. This is useful for some APIs where they do a GET Request when the webhook is first setup and expect a specific Response.

Only use this if you really need to Respond to the Request that comes in. Most of the time you don’t.

Show options

skipTriggeringRuns · boolean · default: false

If you set this to true, the Request that comes in won’t go on to Trigger any Runs. This is useful if you want to Respond to the Request, but don’t want to Trigger any Runs.

filter · RequestFilter

Only Requests that match this filter will cause the corresponding function to run. For example, you can use this to only allow GET Requests.

Show options

method · array

An array of HTTP methods to match. For example, ["GET", "POST"] will match both GET and POST Requests.

query · object

An object of query parameters to match. This uses the EventFilter matching syntax.

filter: {
  query: {
    "hub.mode": [{ $startsWith: "sub" }],
  },
},

headers · object

An object of header key/values to match. This uses the EventFilter matching syntax.

filter: {
  header: {
    "content-type": ["application/json"],
  },
},

body · object

An object of key/values to match. This uses the EventFilter matching syntax.

handler · function · required

This is a function that’s called when a Request comes in. It’s passed the Request object, and expects you to return a Response object.

Returns

HttpEndpoint · HttpEndpoint

The HTTP Endpoint that was created. You should assign this to a variable, as you’ll need it to create an HTTP Trigger.