Waitpoint token callback URLs (#2025)

* Initial commit with a plan for what we’re going to do

* Some initial types and improved plan

* Add Waitpoint resolver

* Add resolver + status index

* Remove type + status index

* Only drop if exists

* Remove type index

* Update waitpoint list presenter to use resolver

* Added resolver to the engine

* Made the existing waitpoint list presenter more flexible

* Initial implentation ofr wait.forHttpCallback()

* Added the callback endpoint (no API rate limit)

* schema version

* Added jsdocs, removed schema version because of errors

* Show callback URL if it’s set

* Dashboard pages and panels

* Remove todos

* Added temporary icon

* Added a blank state

* Some tweaks and added a Replicate example

* Implement unwrap() for httpCallback

* Added unwrap to wait.forToken() as well

* Improved jsdocs

* Added docs

* Added unwrap to the token docs

* Show a dash if there are no tags

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Make the timeout error safer

* Fixed migrations… should use id desc not createdAt desc

* Fixed page title

* Fixed migration so it only adds them if they don’t exist. This allows us to manuall run in cloud first

* Respect the max content length by getting the length of the body

* Added more docs details about the callback format

* Remove code comment

* Improved the error

* Added a hash to the HTTP callback URLs

* Add the apiKey to the API input type to fix TS error

* Return the error responses. They were being caught and not preserved

* The content-length header is required. Deal with an empty body

* Removed unused types

* Added some new span icons

* Reworked http callback to be a create call then just use wait.forToken()

* Added a changeset

* Updated the docs

* Updated the wait overview docs

* Simplify to just a call

* WIP stripping right back to waitpoints just having a URL associated with them…

* More deletions

* Remove missing icon

* Updated the changeset

* Add URL to the token return types

* Remove wait for http callback page

* Updated docs

* More tidying

* Type and import fix

* Remove unused import

* Some type fixes for the retrieve

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: matt-aitken

.changeset/curvy-dogs-share.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+When you create a Waitpoint token using `wait.createToken()` you get a URL back that can be used to complete it by making an HTTP POST request.

apps/webapp/app/components/runs/v3/RunIcon.tsx

@@ -19,6 +19,7 @@ import { FunctionIcon } from "~/assets/icons/FunctionIcon";
 import { TriggerIcon } from "~/assets/icons/TriggerIcon";
 import { PythonLogoIcon } from "~/assets/icons/PythonLogoIcon";
 import { TraceIcon } from "~/assets/icons/TraceIcon";
+import { WaitpointTokenIcon } from "~/assets/icons/WaitpointTokenIcon";
 
 type TaskIconProps = {
   name: string | undefined;
@@ -75,6 +76,10 @@ export function RunIcon({ name, className, spanName }: TaskIconProps) {
       return <TriggerIcon className={cn(className, "text-orange-500")} />;
     case "python":
       return <PythonLogoIcon className={className} />;
+    case "wait-token":
+      return <WaitpointTokenIcon className={cn(className, "text-sky-500")} />;
+    case "function":
+      return <FunctionIcon className={cn(className, "text-text-dimmed")} />;
     //log levels
     case "debug":
     case "log":

apps/webapp/app/components/runs/v3/WaitpointDetails.tsx

@@ -11,6 +11,7 @@ import { v3WaitpointTokenPath, v3WaitpointTokensPath } from "~/utils/pathBuilder
 import { PacketDisplay } from "./PacketDisplay";
 import { WaitpointStatusCombo } from "./WaitpointStatus";
 import { RunTag } from "./RunTag";
+import { ClipboardField } from "~/components/primitives/ClipboardField";
 
 export function WaitpointDetailTable({
   waitpoint,
@@ -50,6 +51,14 @@ export function WaitpointDetailTable({
           )}
         </Property.Value>
       </Property.Item>
+      {waitpoint.type === "MANUAL" && (
+        <Property.Item>
+          <Property.Label>Callback URL</Property.Label>
+          <Property.Value className="my-1">
+            <ClipboardField value={waitpoint.url} variant={"secondary/small"} />
+          </Property.Value>
+        </Property.Item>
+      )}
       <Property.Item>
         <Property.Label>Idempotency key</Property.Label>
         <Property.Value>

apps/webapp/app/presenters/v3/ApiWaitpointTokenListPresenter.server.ts renamed to apps/webapp/app/presenters/v3/ApiWaitpointListPresenter.server.ts

@@ -1,16 +1,12 @@
-import { RuntimeEnvironmentType, WaitpointTokenStatus } from "@trigger.dev/core/v3";
+import { type RuntimeEnvironmentType, WaitpointTokenStatus } from "@trigger.dev/core/v3";
+import { type RunEngineVersion, type WaitpointResolver } from "@trigger.dev/database";
 import { z } from "zod";
-import { BasePresenter } from "./basePresenter.server";
 import { CoercedDate } from "~/utils/zod";
-import { AuthenticatedEnvironment } from "@internal/run-engine";
-import {
-  WaitpointTokenListOptions,
-  WaitpointTokenListPresenter,
-} from "./WaitpointTokenListPresenter.server";
 import { ServiceValidationError } from "~/v3/services/baseService.server";
-import { RunEngineVersion } from "@trigger.dev/database";
+import { BasePresenter } from "./basePresenter.server";
+import { type WaitpointListOptions, WaitpointListPresenter } from "./WaitpointListPresenter.server";
 
-export const ApiWaitpointTokenListSearchParams = z.object({
+export const ApiWaitpointListSearchParams = z.object({
   "page[size]": z.coerce.number().int().positive().min(1).max(100).optional(),
   "page[after]": z.string().optional(),
   "page[before]": z.string().optional(),
@@ -61,9 +57,9 @@ export const ApiWaitpointTokenListSearchParams = z.object({
   "filter[createdAt][to]": CoercedDate,
 });
 
-type ApiWaitpointTokenListSearchParams = z.infer<typeof ApiWaitpointTokenListSearchParams>;
+type ApiWaitpointListSearchParams = z.infer<typeof ApiWaitpointListSearchParams>;
 
-export class ApiWaitpointTokenListPresenter extends BasePresenter {
+export class ApiWaitpointListPresenter extends BasePresenter {
   public async call(
     environment: {
       id: string;
@@ -72,11 +68,12 @@ export class ApiWaitpointTokenListPresenter extends BasePresenter {
         id: string;
         engine: RunEngineVersion;
       };
+      apiKey: string;
     },
-    searchParams: ApiWaitpointTokenListSearchParams
+    searchParams: ApiWaitpointListSearchParams
   ) {
     return this.trace("call", async (span) => {
-      const options: WaitpointTokenListOptions = {
+      const options: WaitpointListOptions = {
         environment,
       };
 
@@ -118,7 +115,7 @@ export class ApiWaitpointTokenListPresenter extends BasePresenter {
         options.to = searchParams["filter[createdAt][to]"].getTime();
       }
 
-      const presenter = new WaitpointTokenListPresenter();
+      const presenter = new WaitpointListPresenter();
       const result = await presenter.call(options);
 
       if (!result.success) {

apps/webapp/app/presenters/v3/ApiWaitpointPresenter.server.ts

@@ -2,8 +2,8 @@ import { logger, type RuntimeEnvironmentType } from "@trigger.dev/core/v3";
 import { type RunEngineVersion } from "@trigger.dev/database";
 import { ServiceValidationError } from "~/v3/services/baseService.server";
 import { BasePresenter } from "./basePresenter.server";
-import { WaitpointPresenter } from "./WaitpointPresenter.server";
-import { waitpointStatusToApiStatus } from "./WaitpointTokenListPresenter.server";
+import { waitpointStatusToApiStatus } from "./WaitpointListPresenter.server";
+import { generateHttpCallbackUrl } from "~/services/httpCallback.server";
 
 export class ApiWaitpointPresenter extends BasePresenter {
   public async call(
@@ -14,6 +14,7 @@ export class ApiWaitpointPresenter extends BasePresenter {
         id: string;
         engine: RunEngineVersion;
       };
+      apiKey: string;
     },
     waitpointId: string
   ) {
@@ -24,6 +25,7 @@ export class ApiWaitpointPresenter extends BasePresenter {
           environmentId: environment.id,
         },
         select: {
+          id: true,
           friendlyId: true,
           type: true,
           status: true,
@@ -62,6 +64,7 @@ export class ApiWaitpointPresenter extends BasePresenter {
       return {
         id: waitpoint.friendlyId,
         type: waitpoint.type,
+        url: generateHttpCallbackUrl(waitpoint.id, environment.apiKey),
         status: waitpointStatusToApiStatus(waitpoint.status, waitpoint.outputIsError),
         idempotencyKey: waitpoint.idempotencyKey,
         userProvidedIdempotencyKey: waitpoint.userProvidedIdempotencyKey,

apps/webapp/app/presenters/v3/WaitpointTokenListPresenter.server.ts renamed to apps/webapp/app/presenters/v3/WaitpointListPresenter.server.ts

@@ -1,6 +1,7 @@
 import parse from "parse-duration";
 import {
   Prisma,
+  type WaitpointResolver,
   type RunEngineVersion,
   type RuntimeEnvironmentType,
   type WaitpointStatus,
@@ -11,17 +12,19 @@ import { BasePresenter } from "./basePresenter.server";
 import { type WaitpointSearchParams } from "~/components/runs/v3/WaitpointTokenFilters";
 import { determineEngineVersion } from "~/v3/engineVersion.server";
 import { type WaitpointTokenStatus, type WaitpointTokenItem } from "@trigger.dev/core/v3";
+import { generateHttpCallbackUrl } from "~/services/httpCallback.server";
 
 const DEFAULT_PAGE_SIZE = 25;
 
-export type WaitpointTokenListOptions = {
+export type WaitpointListOptions = {
   environment: {
     id: string;
     type: RuntimeEnvironmentType;
     project: {
       id: string;
       engine: RunEngineVersion;
     };
+    apiKey: string;
   };
   // filters
   id?: string;
@@ -63,7 +66,7 @@ type Result =
       filters: undefined;
     };
 
-export class WaitpointTokenListPresenter extends BasePresenter {
+export class WaitpointListPresenter extends BasePresenter {
   public async call({
     environment,
     id,
@@ -76,7 +79,7 @@ export class WaitpointTokenListPresenter extends BasePresenter {
     direction = "forward",
     cursor,
     pageSize = DEFAULT_PAGE_SIZE,
-  }: WaitpointTokenListOptions): Promise<Result> {
+  }: WaitpointListOptions): Promise<Result> {
     const engineVersion = await determineEngineVersion({ environment });
     if (engineVersion === "V1") {
       return {
@@ -165,8 +168,8 @@ export class WaitpointTokenListPresenter extends BasePresenter {
       ${sqlDatabaseSchema}."Waitpoint" w
     WHERE
       w."environmentId" = ${environment.id}
-      AND w.type = 'MANUAL'
-      -- cursor
+    AND w.type = 'MANUAL'      
+    -- cursor
       ${
         cursor
           ? direction === "forward"
@@ -263,6 +266,7 @@ export class WaitpointTokenListPresenter extends BasePresenter {
       success: true,
       tokens: tokensToReturn.map((token) => ({
         id: token.friendlyId,
+        url: generateHttpCallbackUrl(token.id, environment.apiKey),
         status: waitpointStatusToApiStatus(token.status, token.outputIsError),
         completedAt: token.completedAt ?? undefined,
         timeoutAt: token.completedAfter ?? undefined,

apps/webapp/app/presenters/v3/WaitpointPresenter.server.ts

@@ -1,8 +1,9 @@
 import { isWaitpointOutputTimeout, prettyPrintPacket } from "@trigger.dev/core/v3";
+import { generateHttpCallbackUrl } from "~/services/httpCallback.server";
 import { logger } from "~/services/logger.server";
 import { BasePresenter } from "./basePresenter.server";
 import { type RunListItem, RunListPresenter } from "./RunListPresenter.server";
-import { waitpointStatusToApiStatus } from "./WaitpointTokenListPresenter.server";
+import { waitpointStatusToApiStatus } from "./WaitpointListPresenter.server";
 
 export type WaitpointDetail = NonNullable<Awaited<ReturnType<WaitpointPresenter["call"]>>>;
 
@@ -22,6 +23,7 @@ export class WaitpointPresenter extends BasePresenter {
         environmentId,
       },
       select: {
+        id: true,
         friendlyId: true,
         type: true,
         status: true,
@@ -42,6 +44,11 @@ export class WaitpointPresenter extends BasePresenter {
           take: 5,
         },
         tags: true,
+        environment: {
+          select: {
+            apiKey: true,
+          },
+        },
       },
     });
 
@@ -83,6 +90,7 @@ export class WaitpointPresenter extends BasePresenter {
     return {
       id: waitpoint.friendlyId,
       type: waitpoint.type,
+      url: generateHttpCallbackUrl(waitpoint.id, waitpoint.environment.apiKey),
       status: waitpointStatusToApiStatus(waitpoint.status, waitpoint.outputIsError),
       idempotencyKey: waitpoint.idempotencyKey,
       userProvidedIdempotencyKey: waitpoint.userProvidedIdempotencyKey,

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.waitpoints.tokens/route.tsx

@@ -7,6 +7,7 @@ import { NoWaitpointTokens } from "~/components/BlankStatePanels";
 import { MainCenteredContainer, PageBody, PageContainer } from "~/components/layout/AppLayout";
 import { ListPagination } from "~/components/ListPagination";
 import { LinkButton } from "~/components/primitives/Buttons";
+import { ClipboardField } from "~/components/primitives/ClipboardField";
 import { CopyableText } from "~/components/primitives/CopyableText";
 import { DateTime } from "~/components/primitives/DateTime";
 import { NavBar, PageAccessories, PageTitle } from "~/components/primitives/PageHeader";
@@ -36,7 +37,7 @@ import { useOrganization } from "~/hooks/useOrganizations";
 import { useProject } from "~/hooks/useProject";
 import { findProjectBySlug } from "~/models/project.server";
 import { findEnvironmentBySlug } from "~/models/runtimeEnvironment.server";
-import { WaitpointTokenListPresenter } from "~/presenters/v3/WaitpointTokenListPresenter.server";
+import { WaitpointListPresenter } from "~/presenters/v3/WaitpointListPresenter.server";
 import { requireUserId } from "~/services/session.server";
 import { docsPath, EnvironmentParamSchema, v3WaitpointTokenPath } from "~/utils/pathBuilder";
 
@@ -84,7 +85,7 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
   }
 
   try {
-    const presenter = new WaitpointTokenListPresenter();
+    const presenter = new WaitpointListPresenter();
     const result = await presenter.call({
       environment,
       ...searchParams,
@@ -143,6 +144,7 @@ export default function Page() {
                       <TableRow>
                         <TableHeaderCell className="w-[1%]">Created</TableHeaderCell>
                         <TableHeaderCell className="w-[20%]">ID</TableHeaderCell>
+                        <TableHeaderCell className="w-[20%]">Callback URL</TableHeaderCell>
                         <TableHeaderCell className="w-[20%]">Status</TableHeaderCell>
                         <TableHeaderCell className="w-[20%]">Completed</TableHeaderCell>
                         <TableHeaderCell className="w-[20%]">Idempotency Key</TableHeaderCell>
@@ -178,6 +180,9 @@ export default function Page() {
                               <TableCell to={path}>
                                 <CopyableText value={token.id} className="font-mono" />
                               </TableCell>
+                              <TableCell to={path}>
+                                <ClipboardField value={token.url} variant={"secondary/small"} />
+                              </TableCell>
                               <TableCell to={path}>
                                 <WaitpointStatusCombo status={token.status} className="text-xs" />
                               </TableCell>

apps/webapp/app/routes/api.v1.waitpoints.tokens.$waitpointFriendlyId.callback.$hash.ts

@@ -0,0 +1,91 @@
+import { type ActionFunctionArgs, json } from "@remix-run/server-runtime";
+import {
+  type CompleteWaitpointTokenResponseBody,
+  conditionallyExportPacket,
+  stringifyIO,
+} from "@trigger.dev/core/v3";
+import { WaitpointId } from "@trigger.dev/core/v3/isomorphic";
+import { z } from "zod";
+import { $replica } from "~/db.server";
+import { env } from "~/env.server";
+import { verifyHttpCallbackHash } from "~/services/httpCallback.server";
+import { logger } from "~/services/logger.server";
+import { engine } from "~/v3/runEngine.server";
+
+const paramsSchema = z.object({
+  waitpointFriendlyId: z.string(),
+  hash: z.string(),
+});
+
+export async function action({ request, params }: ActionFunctionArgs) {
+  if (request.method.toUpperCase() !== "POST") {
+    return json({ error: "Method not allowed" }, { status: 405, headers: { Allow: "POST" } });
+  }
+
+  const contentLength = request.headers.get("content-length");
+  if (!contentLength) {
+    return json({ error: "Content-Length header is required" }, { status: 411 });
+  }
+
+  if (parseInt(contentLength) > env.TASK_PAYLOAD_MAXIMUM_SIZE) {
+    return json({ error: "Request body too large" }, { status: 413 });
+  }
+
+  const { waitpointFriendlyId, hash } = paramsSchema.parse(params);
+  const waitpointId = WaitpointId.toId(waitpointFriendlyId);
+
+  try {
+    const waitpoint = await $replica.waitpoint.findFirst({
+      where: {
+        id: waitpointId,
+      },
+      include: {
+        environment: {
+          select: {
+            apiKey: true,
+          },
+        },
+      },
+    });
+
+    if (!waitpoint) {
+      return json({ error: "Waitpoint not found" }, { status: 404 });
+    }
+
+    if (!verifyHttpCallbackHash(waitpoint.id, hash, waitpoint.environment.apiKey)) {
+      return json({ error: "Invalid URL, hash doesn't match" }, { status: 401 });
+    }
+
+    if (waitpoint.status === "COMPLETED") {
+      return json<CompleteWaitpointTokenResponseBody>({
+        success: true,
+      });
+    }
+
+    // If the request body is not valid JSON, return an empty object
+    const body = await request.json().catch(() => ({}));
+
+    const stringifiedData = await stringifyIO(body);
+    const finalData = await conditionallyExportPacket(
+      stringifiedData,
+      `${waitpointId}/waitpoint/http-callback`
+    );
+
+    const result = await engine.completeWaitpoint({
+      id: waitpointId,
+      output: finalData.data
+        ? { type: finalData.dataType, value: finalData.data, isError: false }
+        : undefined,
+    });
+
+    return json<CompleteWaitpointTokenResponseBody>(
+      {
+        success: true,
+      },
+      { status: 200 }
+    );
+  } catch (error) {
+    logger.error("Failed to complete HTTP callback", { error });
+    throw json({ error: "Failed to complete HTTP callback" }, { status: 500 });
+  }
+}