Webhook Trigger Node

The Webhook Trigger node turns a workflow into an HTTP entrypoint. When you create the trigger, Builder Studio provisions a secret-protected endpoint. Any inbound request that authenticates with that secret starts an execution of the workflow downstream of the node, seeding the request method, URL, headers, query, and body into the graph.

Create the endpoint

1. 1

   Add a Webhook Trigger node

   Place the node on the canvas. Before you create an endpoint it shows a “No webhook configured” state with a Create webhook endpoint button.

2. 2

   Create the webhook endpoint

   Editors with edit access click Create webhook endpoint. Builder Studio registers a webhook trigger for this canvas and node, and generates the bearer secret used to authenticate inbound calls.

3. 3

   Copy the cURL command

   The copy button writes a ready-to-run cURL command that targets the endpoint with an Authorization: Bearer header. The endpoint URL is shown in the node, but the secret is only included in the copied command and is hidden from viewers without edit access.

4. 4

   Send a test request

   Post an event to the endpoint. The node status row updates and records the last-triggered time when a request successfully starts an execution.

Endpoint and authentication

All triggers for a deployment share one stable path, /webhook/trigger, on the Convex site URL. The secret in the request identifies which trigger (and therefore which canvas and node) to run, so the secret is the credential — treat it like a password.

• Send the secret as Authorization: Bearer <secret> or as an x-webhook-secret header.
• Passing the secret as a ?secret= query parameter is rejected with a 400 so it cannot leak into request logs.
• A missing or unrecognized secret returns 400 or 404. Revoking the endpoint invalidates the secret immediately.

1curl -X POST "https://<your-convex-site>/webhook/trigger" \2  -H "Authorization: Bearer <webhook-secret>" \3  -H "Content-Type: application/json" \4  -d '{"event":"order.created","orderId":"1234"}'

Accepted requests

What downstream nodes receive

The node has no inputs. It exposes the request to the rest of the workflow through six text output ports. Connect the ports you need to downstream nodes.

1// Output ports exposed to downstream nodes (all text):2method-out    // request method, e.g. "POST"3url-out       // sanitized request URL (secret query param stripped)4headers-out   // request headers as JSON (auth/cookie headers redacted)5query-out     // query string params as JSON (secret stripped)6body-out      // parsed JSON/form body re-serialized (callbackUrl removed)7raw-body-out  // the raw request body text as received

Idempotency and provider hints

The trigger can deduplicate retries so a re-delivered event does not run the workflow twice.

• Send an Idempotency-Key (or x-idempotency-key header, or idempotencyKey body field) to make a request idempotent. A replay returns the original response with an Idempotency-Replayed: true header; a key reused with a different body returns 409.
• Known provider headers are recognized to infer a provider and event id automatically, including GitHub (x-github-delivery), Shopify, OpenAI, and Stripe. When a provider and event id are present, the trigger derives an idempotency key for you.
• Include a callbackUrl in the JSON body to have the execution post results back. The callback URL must resolve to a public host or the request is rejected with 400.

Status, revoke, and cleanup

• The status row reflects configuration state (Not configured, Loading, Ready) and execution state (Idle, Running, Triggered, Error), plus the last-triggered time.
• Revoke removes the endpoint and its secret. The node returns to the unconfigured state, and you can create a new endpoint with a fresh secret.
• If the underlying node is deleted or its type changes, the stale trigger is cleaned up and further calls return 404.