feat(webapp,core): webhook response contracts, GET verification and verify tokens

## Summary

Hosted webhook sources can now describe how the provider expects to be
answered, and the ingress honors it. This is the server side for
providers like Discord and WhatsApp, whose SDK sources follow in a later
release.

- A verifier artifact can declare a response contract as data: the
status code for a handshake answer (`respondStatus`), and the codes
returned for accepted deliveries and rejected signatures
(`response.acceptedStatus`, `response.rejectedStatus`). The ingress and
the dashboard's send action map every outcome through the same helper,
so a source that needs 204 on success and 401 on a bad signature gets
exactly that.
- A verifier artifact can declare a GET verification flow
(`getHandshake`) for providers that confirm a callback URL with a
challenge, such as Meta's `hub.challenge`. The ingress answers GET on
the endpoint URL against a dedicated verify token, which you generate
and reveal from the endpoint's Connect panel. The token is its own
credential, separate from the signing secret.
- HMAC verifiers can read the signed timestamp from a body field. The
Linear provider uses it for a 60 second replay window on
`webhookTimestamp`; deliveries are deduplicated on the signed request
itself, so a replay with a different unsigned delivery header is still
recognised as a duplicate.
- The dashboard's test-send re-signs a recorded sample with the current
timestamp, so sources with a body-timestamp replay window accept it.
- An admin API action bootstraps delivery partitions in the configured
webhook database before enablement. It is safe to repeat and preserves
existing partitions. Bootstrap and daily maintenance can use
`WEBHOOK_DATABASE_DIRECT_URL` with separate owner credentials while
application queries use `WEBHOOK_DATABASE_URL`. When the direct URL is
unset, partition operations reuse the webhook writer.
- The index worker protocol gains a message for duplicate webhook ids,
so the CLI can report which files define the same id. The CLI side of
this ships with the SDK release that adds `webhook()`.

Mono-RevId: 54862ef81ec5adc311aa42783020fedc4b8c3ba9

Author: ericallam

.changeset/webhook-artifact-response-contract.md

@@ -0,0 +1,5 @@
+---
+"@trigger.dev/core": patch
+---
+
+Webhook verifier artifacts can now declare the provider's response contract as data: a handshake `respondStatus`, the status codes returned for accepted deliveries and rejected signatures, and a GET verification flow (`getHandshake`) for providers that confirm a callback URL with a challenge. HMAC verifiers can read the timestamp from a body field, which the Linear provider config uses for its replay window, and the dashboard's test-send re-signs a recorded sample as of now so it passes that window.

apps/webapp/app/components/webhookConsole/WebhookComposer.tsx

@@ -19,6 +19,7 @@ import {
 import { Select, SelectItem } from "~/components/primitives/Select";
 import { TabButton, TabContainer } from "~/components/primitives/Tabs";
 import { cn } from "~/utils/cn";
+import type { WebhookHandshakeConfig } from "@trigger.dev/core/v3";
 import type { WebhookSendResult } from "~/routes/resources.orgs.$organizationSlug.projects.$projectParam.env.$envParam.webhooks.endpoints.$endpointParam.send";
 import { AIPayloadTabContent } from "~/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.test.tasks.$taskParam/AIPayloadTabContent";
 import { ReplaySourcePicker } from "./ReplaySourcePicker";
@@ -33,7 +34,7 @@ type WebhookComposerEndpoint = {
   ingressUrl: string;
   scheme: "hmac" | "shared-secret" | "url-secret" | "asymmetric";
   hasSigningSecret: boolean;
-  handshake: { matchPath: string; matchValue: string; respondPath: string } | null;
+  handshake: WebhookHandshakeConfig | null;
 };
 
 export type WebhookComposerProps = {
@@ -369,7 +370,7 @@ export function WebhookComposer({
               variant="tertiary/small"
               onClick={() => sendHandshake()}
               disabled={isSending || !endpoint}
-              tooltip="Send a signed handshake and assert the endpoint echoes the challenge"
+              tooltip="Send a signed handshake and check the endpoint answers it (echoing the challenge, or a bodiless status)"
             >
               Send handshake
             </Button>
@@ -477,12 +478,12 @@ function setPath(target: Record<string, unknown>, path: string, value: unknown)
 }
 
 function buildHandshakeBody(
-  handshake: { matchPath: string; matchValue: string; respondPath: string },
+  handshake: WebhookHandshakeConfig,
   challenge: string
 ): Record<string, unknown> {
   const body: Record<string, unknown> = {};
   setPath(body, handshake.matchPath, handshake.matchValue);
-  setPath(body, handshake.respondPath, challenge);
+  if (handshake.respondPath) setPath(body, handshake.respondPath, challenge);
   return body;
 }
 
@@ -542,7 +543,8 @@ function ResultStrip({
   const status = result.success ? result.httpStatus : undefined;
   const handshake = result.success && result.handshake;
   const deduplicated = result.success && result.deduplicated;
-  const ok = result.success && status === 200 && !deduplicated;
+  const ok =
+    result.success && status !== undefined && status >= 200 && status < 300 && !deduplicated;
   return (
     <div className="flex flex-col gap-2">
       <div className="flex items-center gap-2">
@@ -562,7 +564,7 @@ function ResultStrip({
             ? "Handshake"
             : deduplicated
               ? "Deduplicated"
-              : result.success
+              : result.httpStatus !== undefined
                 ? `HTTP ${result.httpStatus}`
                 : "Failed"}
         </span>
@@ -584,12 +586,15 @@ function ResultStrip({
           Identical payload was deduplicated to the original delivery. Vary it to send a new one.
         </Hint>
       ) : null}
-      <CodeBlock
-        code={result.success ? result.responseBody : result.error}
-        language="json"
-        showLineNumbers={false}
-        maxLines={8}
-      />
+      {!result.success ? <Hint>{result.error}</Hint> : null}
+      {result.responseBody !== undefined ? (
+        <CodeBlock
+          code={result.responseBody}
+          language="json"
+          showLineNumbers={false}
+          maxLines={8}
+        />
+      ) : null}
     </div>
   );
 }

apps/webapp/app/db.server.ts

@@ -172,6 +172,7 @@ type DatasourceLabel =
   | "run-ops-writer"
   | "run-ops-replica"
   | "webhook-writer"
+  | "webhook-partitions"
   | "webhook-replica";
 
 function tagDatasource<T extends PrismaClient>(datasource: DatasourceLabel, client: T): T {
@@ -256,6 +257,26 @@ export const webhookPrisma: WebhookDatabase = singleton("webhookPrisma", () => {
   );
 });
 
+/**
+ * Partition DDL can use a direct connection and an owner role while delivery queries use a
+ * pooled app role. Unset reuses the writer, preserving single-connection installations.
+ */
+export const webhookPartitionPrisma: WebhookDatabase = singleton("webhookPartitionPrisma", () => {
+  if (!env.WEBHOOK_DATABASE_DIRECT_URL) {
+    return webhookPrisma;
+  }
+  return captureInfrastructureErrors(
+    tagDatasource(
+      "webhook-partitions",
+      buildWriterClient({
+        url: env.WEBHOOK_DATABASE_DIRECT_URL,
+        clientType: "webhook-partitions",
+        connectionLimit: 1,
+      })
+    )
+  );
+});
+
 /**
  * Webhook reader chain: an explicit webhook replica, else the webhook writer once split (no
  * separate replica yet), else the main $replica when the feature is not split.

apps/webapp/app/env.server.ts

@@ -376,6 +376,8 @@ const EnvironmentSchema = z
     // Webhook feature data-plane DB (WebhookEndpoint + WebhookDelivery). Unset -> the webhook
     // clients reuse the main prisma / $replica, so this is connection-neutral until you split.
     WEBHOOK_DATABASE_URL: z.string().optional(),
+    // Direct connection with ownership privileges for bootstrap and partition maintenance.
+    WEBHOOK_DATABASE_DIRECT_URL: z.string().optional(),
     WEBHOOK_DATABASE_READ_REPLICA_URL: z.string().optional(),
     WEBHOOK_DATABASE_CONNECTION_LIMIT: z.coerce.number().int().optional(),
     SESSION_SECRET: z.string().min(1).refine(isNotInsecureSecret, INSECURE_SECRET_MESSAGE),

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.webhooks.endpoints.$endpointParam/route.tsx

@@ -51,6 +51,7 @@ import { docsPath, EnvironmentParamSchema, v3WebhookTaskPath } from "~/utils/pat
 import { parseFiniteInt } from "~/utils/searchParams";
 import { FEATURE_FLAG } from "~/v3/featureFlags";
 import { flag } from "~/v3/featureFlags.server";
+import { webhookVerifyTokenKey } from "~/v3/webhookEngine.server";
 
 const EndpointParamSchema = EnvironmentParamSchema.extend({
   endpointParam: z.string(),
@@ -112,6 +113,19 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
   const routing = WebhookRoutingTarget.safeParse(endpoint.routingTarget);
   const verifier = WebhookVerifierArtifact.safeParse(endpoint.verifierArtifact);
 
+  const getHandshake =
+    verifier.success && "getHandshake" in verifier.data ? verifier.data.getHandshake : undefined;
+  const hasVerifyToken = getHandshake
+    ? Boolean(
+        (
+          await getSecretStore("DATABASE", { prismaClient: prisma }).getSecret(
+            VerifyTokenSchema,
+            webhookVerifyTokenKey(endpoint.id)
+          )
+        )?.token
+      )
+    : false;
+
   const url = new URL(request.url);
   const periodParam = url.searchParams.get("period") ?? undefined;
   const from = parseFiniteInt(url.searchParams.get("from"));
@@ -142,6 +156,7 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
     ingestUrl,
     routing: routing.success ? routing.data : null,
     verifier: verifier.success ? verifier.data : null,
+    hasVerifyToken,
     deliveriesList,
   });
 };
@@ -151,6 +166,8 @@ const SetSecretSchema = z.object({
   secret: z.string().trim().min(1, "A signing secret is required"),
 });
 
+const VerifyTokenSchema = z.object({ token: z.string() });
+
 export const action = async ({ request, params }: ActionFunctionArgs) => {
   const { project, environment, endpointParam } = await requireWebhookAccess(request, params);
 
@@ -197,6 +214,21 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
     return { success: true as const, generatedSecret: secret };
   }
 
+  if (intent === "generate-verify-token") {
+    const verifier = WebhookVerifierArtifact.safeParse(endpoint.verifierArtifact);
+    const getHandshake =
+      verifier.success && "getHandshake" in verifier.data ? verifier.data.getHandshake : undefined;
+    if (!getHandshake) {
+      return {
+        success: false as const,
+        error: "This endpoint's source does not verify its URL with a GET request.",
+      };
+    }
+    const token = `whvt_${randomBytes(24).toString("hex")}`;
+    await secretStore.setSecret(webhookVerifyTokenKey(endpoint.id), { token });
+    return { success: true as const, generatedVerifyToken: token };
+  }
+
   // Set/Rotate (paste a provider-supplied secret).
   const submission = SetSecretSchema.safeParse(Object.fromEntries(formData));
   if (!submission.success) {
@@ -212,7 +244,7 @@ export const action = async ({ request, params }: ActionFunctionArgs) => {
 };
 
 export default function Page() {
-  const { endpoint, ingestUrl, routing, verifier, deliveriesList } =
+  const { endpoint, ingestUrl, routing, verifier, hasVerifyToken, deliveriesList } =
     useTypedLoaderData<typeof loader>();
   const organization = useOrganization();
   const project = useProject();
@@ -297,6 +329,7 @@ export default function Page() {
               ingestUrl={ingestUrl}
               routing={routing}
               verifier={verifier}
+              hasVerifyToken={hasVerifyToken}
               handlerPath={handlerPath}
             />
           </ResizablePanel>
@@ -313,10 +346,12 @@ function EndpointSidebar({
   ingestUrl,
   routing,
   verifier,
+  hasVerifyToken,
   handlerPath,
 }: {
   endpoint: WebhookEndpointDetail;
   ingestUrl: string;
+  hasVerifyToken: boolean;
   routing: LoaderData["routing"];
   verifier: LoaderData["verifier"];
   handlerPath: string;
@@ -336,6 +371,8 @@ function EndpointSidebar({
   const canGenerate =
     scheme !== "asymmetric" &&
     (endpoint.secretProvisioning === "integrator" || endpoint.secretProvisioning === "either");
+  const getHandshake =
+    verifier && verifier.kind !== "bundle" ? (verifier.getHandshake ?? undefined) : undefined;
 
   return (
     <div className="grid h-full grid-rows-[auto_1fr] overflow-hidden bg-background-bright">
@@ -381,6 +418,30 @@ function EndpointSidebar({
                 </div>
               </Property.Value>
             </Property.Item>
+            {getHandshake ? (
+              <Property.Item>
+                <Property.Label>Verify token</Property.Label>
+                <Property.Value>
+                  <div className="flex flex-col items-start gap-1.5">
+                    {hasVerifyToken ? (
+                      <span className="flex items-center gap-1.5">
+                        <span className="size-2 rounded-full bg-success" />
+                        <span>Set</span>
+                      </span>
+                    ) : (
+                      <span className="text-warning">
+                        Not set, the provider cannot verify this URL yet
+                      </span>
+                    )}
+                    <GenerateVerifyTokenDialog hasVerifyToken={hasVerifyToken} />
+                    <Hint>
+                      The provider sends a GET with <code>{getHandshake.tokenParam}</code> when you
+                      save the URL; it must carry this token.
+                    </Hint>
+                  </div>
+                </Property.Value>
+              </Property.Item>
+            ) : null}
           </Property.Table>
           <ProviderSetup verifier={verifier} source={endpoint.source} />
         </section>
@@ -732,6 +793,109 @@ function GenerateSecretDialog({ hasSigningSecret }: { hasSigningSecret: boolean
   );
 }
 
+/**
+ * The GET verification token (Meta's `hub.verify_token`) is its own credential, separate from the
+ * signing secret: minted server-side, stored encrypted, revealed once for the provider's Verify
+ * Token field. Regenerating replaces it and the URL must be re-verified in the provider.
+ */
+function GenerateVerifyTokenDialog({ hasVerifyToken }: { hasVerifyToken: boolean }) {
+  const fetcher = useFetcher<typeof action>();
+  const [open, setOpen] = useState(false);
+  const [dismissedToken, setDismissedToken] = useState<string | undefined>(undefined);
+  const [attempted, setAttempted] = useState(false);
+  const isSubmitting = fetcher.state !== "idle";
+
+  /**
+   * The fetcher keeps its last action data for the life of the component, so closing the dialog
+   * remembers which token was already revealed. A reopen then starts on the form again, and only a
+   * newly generated token (which never repeats) is shown.
+   */
+  const latestToken =
+    fetcher.data && "generatedVerifyToken" in fetcher.data
+      ? fetcher.data.generatedVerifyToken
+      : undefined;
+  const generated =
+    latestToken !== undefined && latestToken !== dismissedToken ? latestToken : undefined;
+
+  const onOpenChange = (next: boolean) => {
+    setOpen(next);
+    if (!next) {
+      setDismissedToken(latestToken);
+      setAttempted(false);
+    }
+  };
+  const failure =
+    attempted && fetcher.state === "idle" && fetcher.data && !fetcher.data.success
+      ? fetcher.data
+      : undefined;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogTrigger asChild>
+        <Button variant="secondary/small" LeadingIcon={SparklesIcon}>
+          {hasVerifyToken ? "Regenerate verify token" : "Generate verify token"}
+        </Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          {hasVerifyToken ? "Regenerate verify token" : "Generate verify token"}
+        </DialogHeader>
+        {generated ? (
+          <div className="flex flex-col gap-3 pt-2">
+            <Paragraph variant="small" className="text-warning">
+              Copy this now. It won't be shown again.
+            </Paragraph>
+            <ClipboardField value={generated} variant="secondary/medium" />
+            <Hint>
+              Paste this into the provider's Verify Token field when you save the webhook URL. It is
+              separate from the signing secret.
+            </Hint>
+            <div className="flex justify-end">
+              <Button type="button" variant="primary/small" onClick={() => onOpenChange(false)}>
+                Done
+              </Button>
+            </div>
+          </div>
+        ) : (
+          <fetcher.Form
+            method="post"
+            className="flex flex-col gap-3 pt-2"
+            onSubmit={() => setAttempted(true)}
+          >
+            <input type="hidden" name="intent" value="generate-verify-token" />
+            <Paragraph variant="small" className="text-text-dimmed">
+              The provider verifies this URL with a GET request carrying a verify token. Trigger.dev
+              generates the token, stores it encrypted, and shows it once so you can paste it into
+              the provider.
+              {hasVerifyToken
+                ? " Regenerating replaces the current token; re-verify the URL in the provider afterwards."
+                : ""}
+            </Paragraph>
+            {failure ? (
+              <Paragraph variant="small" className="text-error">
+                {failure.error}
+              </Paragraph>
+            ) : null}
+            <div className="flex justify-end gap-2">
+              <Button
+                type="button"
+                variant="tertiary/small"
+                onClick={() => onOpenChange(false)}
+                disabled={isSubmitting}
+              >
+                Cancel
+              </Button>
+              <Button type="submit" variant="primary/small" disabled={isSubmitting}>
+                {isSubmitting ? "Generating…" : "Generate verify token"}
+              </Button>
+            </div>
+          </fetcher.Form>
+        )}
+      </DialogContent>
+    </Dialog>
+  );
+}
+
 function TableLoading() {
   return (
     <div className="flex h-full items-center justify-center">