Webhooks

Run workflows when systems POST webhooks.

A webhook trigger runs a workflow or agent when an external system POSTs a request to its endpoint. It’s the primary way to react to events from other services: signups, payments, CI events, and the like.

Example requests

Ask your coding agent which external event should kick off a run. It can create the endpoint and validate the payload.

“When Stripe sends a payment succeeded webhook, update the customer record and start onboarding.”

“When we get a new GitHub issue, triage it and add the right labels.”

“When our app POSTs a new signup, enrich the profile and notify the sales channel.”

Define a webhook

Use defineWebhookSource with a slug, name, description, an endpoint, and a payload schema, then attach a target.

src/triggers/signup.ts

import { defineWebhookSource } from "@keystrokehq/keystroke/trigger";
import { z } from "zod";
import workflow from "../workflows/signup-pipeline";

export default defineWebhookSource({
  slug: "signup",
  name: "Signup",
  description: "Fires when a new signup is posted.",
  endpoint: "signup",
  payload: z.object({
    name: z.string().trim().min(1),
    email: z.string().email(),
  }),
}).attach({ workflow });

Option	Required	What it does
slug	Yes	Stable trigger slug (used in the attachment id and run history)
name	Yes	Human-readable label shown in the platform
description	Yes	What the webhook listens for, shown in the platform
endpoint	Yes	The route suffix; the webhook URL is POST /triggers/{endpoint}
payload	Yes	Zod schema the incoming body must match for the trigger to fire

The webhook URL

The endpoint becomes the route POST /triggers/{endpoint}. Print the full URL for a deployed trigger:

keystroke triggers url signup

Send a test request with the URL from keystroke triggers url, or fire the webhook path from the CLI or the trigger detail Invoke button. The body is validated against the same attachment payload schema:

keystroke triggers invoke signup --input '{"name":"Ada","email":"[e-mail]"}'
keystroke triggers invoke signup --input '{"name":"Ada","email":"[e-mail]"}' --workflow signup-pipeline

When the body matches payload, the trigger fires and starts a run. When it doesn’t, the request is rejected (or skipped, on a shared endpoint).

Webhooks ack asynchronously: the POST returns immediately — 202 with the runId when a trigger matches, or { ok: true, skipped: true } when none does — and the run executes in the background. The workflow’s output is not returned in the webhook response (there’s no “respond to webhook”). To return data to the caller, make an outbound call from the workflow, or have the caller poll the run via run history or the runs API.

Authenticating webhooks

Each webhook route requires a webhook API key. keystroke triggers url returns the full URL with that key already included as a ?token= query parameter, so you can hand it straight to the sending system:

keystroke triggers url signup

If the sender prefers a header to the query parameter, pass the same key one of these ways:

Form	Example
Query	?token=<key> or ?api_key=<key>
Header	Authorization: Bearer <key>
Header	x-api-key: <key>

A request with a missing or invalid key is rejected with 401.

Validation

The payload schema is both the contract and the gate: only requests that parse against it fire the trigger. Model just the fields you care about; extra fields are allowed at every object level when the schema is persisted for ingress matching, so you don’t have to describe an entire third-party payload.

To narrow which events fire (for example, only invoice.paid), put those constraints in the payload schema itself — literals, enums, and string refinements all work:

payload: z.object({
  type: z.literal("invoice.paid"),
  data: z.object({ id: z.string() }),
}),

Exportable schemas

Webhook payload schemas are exported to JSON Schema at build time for platform matching, the canvas, and run forms. They must be plain structural Zod — objects, strings, literals, unions, and built-in validators like .email() or .min(). Do not use code-based methods like .transform(), .preprocess(), .refine(), or .superRefine(); keystroke build will fail with an error explaining the fix.

When you need to remap or normalize fields (for example, coalescing two payload keys into one), keep the exported schema as the wire shape and remap in .attach({ transform }) or with a plain function at the top of run(). See advanced triggers — transform a workflow input.

const WebhookPayload = z.object({
  landing_page_url: z.string().nullable().optional(),
  bootcamp_landing_page: z.string().nullable().optional(),
  email: z.string().email(),
});

export default defineWebhookSource({
  slug: "bootcamp-ae",
  name: "Bootcamp AE",
  description: "Fires when a bootcamp signup webhook arrives.",
  endpoint: "bootcamp-ae",
  payload: WebhookPayload,
}).attach({
  workflow,
  transform: (payload) => ({
    email: payload.email,
    landing_page_url: payload.landing_page_url ?? payload.bootcamp_landing_page ?? null,
  }),
});

The same rule applies to workflow input and output schemas when they are exported at build time. The matched payload type flows into transform and agent prompt callbacks.

Shared endpoints

Multiple trigger files can share the same endpoint: one URL, many triggers, each with its own slug, payload, and transform. This is the pattern for a provider like Stripe that sends every event type to a single webhook URL.

// src/triggers/stripe-invoice-paid.ts  (endpoint: "stripe")
// src/triggers/stripe-subscription-deleted.ts  (endpoint: "stripe", different slug/payload)

Each incoming request is matched against every trigger on the endpoint; matching ones fire, and a payload that matches none returns { ok: true, skipped: true } and records a skipped run per trigger (with validation detail) so you can debug with keystroke triggers runs list <slug> --outcome skipped. List the triggers on a shared endpoint:

keystroke triggers list --endpoint stripe
keystroke triggers url stripe          # one URL for the shared route

Use each trigger’s own slug for run history (keystroke triggers runs list stripe-invoice-paid --workflow <workflow-slug>).

Next steps

Advanced triggers

Transform payloads, attach agents, and interpolate prompts.

App events

Point a webhook at a connected third-party app.

Schedules

Run on a cron schedule instead of an inbound request.

Triggers overview

Sources, attach, and attachment ids.