Webhooks

BuilderStudio supports webhooks in both directions: inbound webhooks that start a workflow when an external system calls BuilderStudio, and outbound callbacks that POST a run's result to a URL you supply when it triggers.

Inbound: webhook triggers

A webhook-trigger nodeon a canvas exposes a stable endpoint. Calling that endpoint with the node's secret starts an execution and passes the request body in as the workflow's inputs.

1. 1

   Add a webhook-trigger node

   Place a webhook-trigger node on the canvas that should run when the webhook fires.

2. 2

   Register the webhook

   Call POST /api/mcp/webhooks/register with { canvasId, triggerNodeId } (scope write:canvas). It returns the webhookUrl, the webhookSecret, and a ready-made webhookAuthorizationHeader value. This step is also available as an MCP tool.

3. 3

   Call the webhook URL

   External systems POST to /webhook/trigger with the secret. BuilderStudio fires the trigger node and starts the run.

1# 1. Register (returns webhookUrl + webhookSecret)2curl -X POST https://<deployment>.convex.site/api/mcp/webhooks/register \3  -H "Authorization: Bearer builder_..." \4  -H "Content-Type: application/json" \5  -d '{ "canvasId": "<id>", "triggerNodeId": "<webhookTriggerNodeClientId>" }'6 7# -> { "webhookUrl": "https://<deployment>.convex.site/webhook/trigger",8#      "webhookSecret": "...", "webhookAuthorizationHeader": "Bearer ...",9#      "triggerNodeId": "...", "created": true }10 11# 2. Fire it (authenticate with the per-trigger secret)12curl -X POST "https://<deployment>.convex.site/webhook/trigger" \13  -H "Authorization: Bearer <webhookSecret>" \14  -H "Content-Type: application/json" \15  -d '{ "topic": "new signup", "callbackUrl": "https://example.com/hook" }'

• Methods: /webhook/trigger accepts GET, POST, PUT, PATCH, and DELETE (plus OPTIONS for CORS).
• Body: JSON or application/x-www-form-urlencoded. The parsed body becomes the workflow inputs. Payloads are capped (about 512 KB).
• callbackUrl: if the body includes a callbackUrl field, it is stripped from the inputs and used to deliver the outbound callback described below.

Outbound: result callbacks

Both POST /api/run and inbound webhook triggers accept an optional callbackUrl. When the execution reaches a terminal state, BuilderStudio sends a single POST to that URL carrying the result payload. This lets you trigger a run asynchronously and be notified when it finishes instead of polling.

• The callbackUrl must be a valid HTTPS URL pointing to a public host. Private and loopback hosts are rejected.
• Delivery is a single POST attempt with the execution result body.

Verifying callback authenticity

When a callback signing secret is configured for the deployment, outbound callbacks are signed with HMAC-SHA256 and carry these headers so you can verify them:

1X-BuilderStudio-Signature             sha256=<hex>   (v1)2X-BuilderStudio-Signature-V2          sha256=<hex>   (v2)3X-BuilderStudio-Signature-Timestamp   <unix ms>4X-BuilderStudio-Signature-Nonce       <nonce>

Calling external webhooks from a workflow

To call an outside service from a running workflow, BuilderStudio provides an SSRF-guarded outbound proxy at POST /api/webhook-relay. It validates the destination against an allowlist, pins DNS, follows a bounded number of redirects, and strips credential-bearing headers on cross-origin redirects. Access requires a signed-in session or a service bearer token; it is used by workflow execution rather than called directly with a builder_ key.

Provider webhooks BuilderStudio receives

BuilderStudio also receives webhooks from integrated providers. These are not part of your programmatic surface — they are verified by the provider's own signature scheme:

• GitHub — POST /api/webhooks/github, verified by the GitHub App HMAC signature (X-Hub-Signature-256).
• Stripe — POST /api/stripe/webhooks and /api/stripe/plan-webhooks, verified by the Stripe signing secret.