Create a webhook waiter

POST

api

webhooks

endpoints

{endpointId}

waiters

TypeScript

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

const waiter = await webhooks.waiter.create(stripe, {
  match: { "event.data.object.metadata.orderId": orderId },
  timeout: "1h",
});

// Wait on it inside a task
const { event } = await webhooks.waiter.wait(waiter.id).unwrap();

curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/waiters" \
  -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"match": {"event.data.object.metadata.orderId": "order_123"}, "timeout": "1h"}'

import requests

url = "https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters"

payload = {
    "match": {
        "event.type": "payment_intent.succeeded",
        "event.data.object.metadata.orderId": "order_123"
    },
    "filter": "event.data.object.amount > 1000",
    "timeout": "1h",
    "tags": "<string>",
    "idempotencyKey": "<string>",
    "idempotencyKeyTTL": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    match: {
      'event.type': 'payment_intent.succeeded',
      'event.data.object.metadata.orderId': 'order_123'
    },
    filter: 'event.data.object.amount > 1000',
    timeout: '1h',
    tags: '<string>',
    idempotencyKey: '<string>',
    idempotencyKeyTTL: '<string>'
  })
};

fetch('https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'match' => [
        'event.type' => 'payment_intent.succeeded',
        'event.data.object.metadata.orderId' => 'order_123'
    ],
    'filter' => 'event.data.object.amount > 1000',
    'timeout' => '1h',
    'tags' => '<string>',
    'idempotencyKey' => '<string>',
    'idempotencyKeyTTL' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters"

	payload := strings.NewReader("{\n  \"match\": {\n    \"event.type\": \"payment_intent.succeeded\",\n    \"event.data.object.metadata.orderId\": \"order_123\"\n  },\n  \"filter\": \"event.data.object.amount > 1000\",\n  \"timeout\": \"1h\",\n  \"tags\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"idempotencyKeyTTL\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"match\": {\n    \"event.type\": \"payment_intent.succeeded\",\n    \"event.data.object.metadata.orderId\": \"order_123\"\n  },\n  \"filter\": \"event.data.object.amount > 1000\",\n  \"timeout\": \"1h\",\n  \"tags\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"idempotencyKeyTTL\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"match\": {\n    \"event.type\": \"payment_intent.succeeded\",\n    \"event.data.object.metadata.orderId\": \"order_123\"\n  },\n  \"filter\": \"event.data.object.amount > 1000\",\n  \"timeout\": \"1h\",\n  \"tags\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"idempotencyKeyTTL\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "waitpoint_abc123",
  "expiresAt": "2023-11-07T05:31:56Z",
  "isCached": true,
  "url": "<string>"
}

{
  "error": "<string>",
  "code": "webhook_waiter_limit",
  "reason": "environment_limit"
}

{
  "error": "<string>",
  "code": "webhook_waiter_limit",
  "reason": "environment_limit"
}

Authorizations

Authorization

string

header

required

Use a named environment API key. It starts with tr_dev_sk_, tr_prod_sk_, tr_stg_sk_, etc.

Create a named API key in the API Keys section of your Trigger.dev project dashboard. Choose the narrowest access preset that supports your integration.

Our TypeScript SDK will default to using the value of the TRIGGER_SECRET_KEY environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the configure function.

import { configure } from "@trigger.dev/sdk";

configure({ accessToken: "tr_dev_sk_1234" });

Path Parameters

endpointId

string

required

The endpoint's declared id (the id passed to webhooks.endpoint.define) or its wh_ id. A value starting with wh_ is always a generated id, since declared ids can't start with wh_. A declared id names the endpoint's declared instance in the key's environment.

Body

application/json

match

object

Up to five paths, each mapped to the value it must equal. event.* reads the event body, header.* a request header (case-insensitive) and webhook.* the endpoint (id, source, externalRef, tenantId or deliveryId). Omit it to create a waiter with its own url.

Show child attributes

Example:

{
  "event.type": "payment_intent.succeeded",
  "event.data.object.metadata.orderId": "order_123"
}

filter

string

A filter the event must also pass, checked after match.

Example:

"event.data.object.amount > 1000"

timeout

string

A duration such as 30m or 1h, or an ISO 8601 date. Defaults to 24 hours, up to 90 days.

Example:

"1h"

Response

Waiter created, or the existing waiter for this idempotency key

string

required

The waiter's id, which is also its waitpoint id. Wait on it with webhooks.waiter.wait() or wait.forToken().

Example:

"waitpoint_abc123"

expiresAt

string<date-time>

required

When the waiter times out.

isCached

boolean

required

true if an existing waiter was returned for the same idempotencyKey.

url

string

Only for a waiter created without match: the URL to give the provider as its per-request webhook. A delivery to it is verified with the endpoint's source and resumes only this waiter.

⌘I

TypeScript

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

const waiter = await webhooks.waiter.create(stripe, {
  match: { "event.data.object.metadata.orderId": orderId },
  timeout: "1h",
});

// Wait on it inside a task
const { event } = await webhooks.waiter.wait(waiter.id).unwrap();

curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/waiters" \
  -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"match": {"event.data.object.metadata.orderId": "order_123"}, "timeout": "1h"}'

import requests

url = "https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters"

payload = {
    "match": {
        "event.type": "payment_intent.succeeded",
        "event.data.object.metadata.orderId": "order_123"
    },
    "filter": "event.data.object.amount > 1000",
    "timeout": "1h",
    "tags": "<string>",
    "idempotencyKey": "<string>",
    "idempotencyKeyTTL": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    match: {
      'event.type': 'payment_intent.succeeded',
      'event.data.object.metadata.orderId': 'order_123'
    },
    filter: 'event.data.object.amount > 1000',
    timeout: '1h',
    tags: '<string>',
    idempotencyKey: '<string>',
    idempotencyKeyTTL: '<string>'
  })
};

fetch('https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'match' => [
        'event.type' => 'payment_intent.succeeded',
        'event.data.object.metadata.orderId' => 'order_123'
    ],
    'filter' => 'event.data.object.amount > 1000',
    'timeout' => '1h',
    'tags' => '<string>',
    'idempotencyKey' => '<string>',
    'idempotencyKeyTTL' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters"

	payload := strings.NewReader("{\n  \"match\": {\n    \"event.type\": \"payment_intent.succeeded\",\n    \"event.data.object.metadata.orderId\": \"order_123\"\n  },\n  \"filter\": \"event.data.object.amount > 1000\",\n  \"timeout\": \"1h\",\n  \"tags\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"idempotencyKeyTTL\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"match\": {\n    \"event.type\": \"payment_intent.succeeded\",\n    \"event.data.object.metadata.orderId\": \"order_123\"\n  },\n  \"filter\": \"event.data.object.amount > 1000\",\n  \"timeout\": \"1h\",\n  \"tags\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"idempotencyKeyTTL\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"match\": {\n    \"event.type\": \"payment_intent.succeeded\",\n    \"event.data.object.metadata.orderId\": \"order_123\"\n  },\n  \"filter\": \"event.data.object.amount > 1000\",\n  \"timeout\": \"1h\",\n  \"tags\": \"<string>\",\n  \"idempotencyKey\": \"<string>\",\n  \"idempotencyKeyTTL\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "id": "waitpoint_abc123",
  "expiresAt": "2023-11-07T05:31:56Z",
  "isCached": true,
  "url": "<string>"
}

{
  "error": "<string>",
  "code": "webhook_waiter_limit",
  "reason": "environment_limit"
}

{
  "error": "<string>",
  "code": "webhook_waiter_limit",
  "reason": "environment_limit"
}

API reference

Tasks API

Batches API

Runs API

Bulk actions API

Errors API

Webhooks API

Queues API

Concurrency limits API

Schedules API

Env Vars API

Deployments API

Waitpoints API

Sessions API

Query API

Create a webhook waiter

Authorizations

Path Parameters

Body

Response