Automation
Webhook triggers
A webhook trigger starts a flow when another service sends an HTTP request to it: a payment provider reporting a payment, a shipping service reporting a delivery, a form tool reporting a submission. Every request is verified with a workspace secret before anything runs, so only the sender you configured can start the flow.
Adding a webhook trigger
- 1Store the key you share with the sender under Workspace settings → Secrets. Depending on the sender this is a token, a signing secret or an access key.
- 2In the flow editor, add a trigger and choose
Webhook. TheWebhook Triggerpanel opens. - 3Choose a
Verificationmethod (see below), select theWorkspace secret, and fill in the settings of that method.Savestays disabled until a secret is selected. - 4Optionally add an
Optional event filterso that only the events you care about start the flow, then clickSave. - 5Copy the
Webhook URLwith the copy button in the field and enter it in the sending service as its webhook, notification or callback URL.
POST https://<workspace-api>/webhooks/<workspaceId>/<flowId>/<triggerKey>Each webhook trigger has its own URL, verification method and secret, and a flow can have several of them. The URL works as soon as the trigger is saved; publishing an app is not required.
The secret of a webhook trigger is only used to check incoming requests and is never sent anywhere, so it doesn't need allowed hosts.
Verification methods
Every request has to prove that it comes from your sender. Pick the method the sender supports:
Bearer token: the sender puts the shared key in anAuthorization: Bearer <key>header. The simplest option, for services where you can set a header yourself.HMAC-SHA256: the sender signs the raw request body with the shared key and sends the signature in a header. The key itself never travels with the request.Stripe: Stripe's own signature scheme, including a timestamp check against replayed requests.Payload checksum (SHA-256): for senders that put a SHA-256 checksum inside the JSON body instead of a header, computed from body fields plus the shared key.
A request that fails verification never starts the flow. The sender gets status 401 and, for most providers, retries later.
Bearer token
Store a long random token as a secret and select it. Every request must carry exactly Bearer , followed by the token, in the Authorization header:
curl -X POST "https://<workspace-api>/webhooks/<workspaceId>/<flowId>/<triggerKey>" \
-H "Authorization: Bearer <your-token>" \
-H "Content-Type: application/json" \
-d '{"event":"form.submitted","formId":"contact","email":"ada@example.com"}'Anyone who knows the token can start the flow. Prefer HMAC-SHA256, a payload checksum or the Stripe preset when the sender supports them.
HMAC-SHA256
The sender computes an HMAC-SHA256 of the exact request body bytes with the shared key, encodes it as lowercase hex, and sends it in a header. Two settings describe where to find it:
Signature header: the header name in lowercase, e.g.x-signature.Signature prefix: optional text in front of the hex value, e.g.sha256=for senders that sendsha256=<hex>. Up to 32 characters.
With the key whk_demo_7f3a9c, a sender signs and sends an invoice event like this:
import { createHmac } from "node:crypto";
const body = JSON.stringify({ event: "invoice.paid", invoiceId: "INV-311", amount: 4900 });
const signature = createHmac("sha256", "whk_demo_7f3a9c").update(body).digest("hex");
await fetch(webhookUrl, {
method: "POST",
headers: { "Content-Type": "application/json", "x-signature": "sha256=" + signature },
body,
});POST /webhooks/<workspaceId>/<flowId>/<triggerKey>
Content-Type: application/json
x-signature: sha256=3bdeb362b1b95224a744fc9a82a3701aeef9df1700dfa930e3c5476f6ef6e1d5
{"event":"invoice.paid","invoiceId":"INV-311","amount":4900}The signature covers the exact bytes. If anything re-formats the JSON between signing and sending, verification fails. HMAC-SHA256 has no timestamp, so on its own it can't tell a replayed request from a new one.
Stripe
- 1In the Stripe dashboard, add a webhook destination with the trigger's
Webhook URLand select the events to receive. - 2Copy the destination's signing secret (
whsec_…) and store it as a workspace secret. - 3In the trigger, choose
Stripeand select that secret.
- The signature in the
Stripe-Signatureheader is checked against the raw body, and its timestamp must be within five minutes. - The body must be a Stripe event with
idandtype. The event id becomes thedeliveryId, so a retried event keeps its id. - A Stripe API key (
sk_…) is not a signing secret and won't verify anything.
state.body.type === "checkout.session.completed"Payload checksum
Some senders don't sign with a header. They add a checksum field to the JSON body, computed from a few body fields and the shared key. You tell the trigger which fields to use, in which order, and how the key is added; it then recomputes the checksum for every request.
Checksum field: dot path of the field that holds the checksum, e.g.notification.signature.Signed fields (in order): comma-separated dot paths. Their values are joined without separators, in exactly this order. End a path with?if the sender leaves it out on some events; any other missing field fails verification. The checksum field can't be one of the signed fields.Secret position:After the fields(default) orBefore the fields.Secret format:As stored(default) orReversed, for senders that reverse the key before hashing.
The trigger hashes the joined string with SHA-256 and compares the lowercase hex result with the checksum field, ignoring upper and lower case. Field values may be text, numbers or booleans. Numbers are used exactly as they appear in the body, so long IDs and amounts like 12.50 produce the same string as on the sender's side.
Example: a parcel tracking service
A shipping service sends delivery updates. Its documentation says the signature is sha256(key + notification.id + notification.kind + status.code + shipment.weight_grams + shipment.carrier), and that weight and carrier are only included for shipment events. Configure the trigger like this:
Verification Payload checksum (SHA-256)
Workspace secret Parcel tracking webhook key
Checksum field notification.signature
Signed fields notification.id, notification.kind, status.code, shipment.weight_grams?, shipment.carrier?
Secret position Before the fields
Secret format As storedA delivery event arrives with this body:
{
"notification": {
"id": 48213377204519873,
"kind": "SHIPMENT_DELIVERED",
"signature": "2fa0af8dd88134eaf6867d912817eb9f7979dfac7028f8c7cc83931d682d4041"
},
"status": { "code": "OK" },
"shipment": {
"reference": "ORD-2041",
"weight_grams": 2350,
"carrier": "ACME"
}
}With the stored key whk_demo_7f3a9c, the trigger puts the key first and appends the five values:
whk_demo_7f3a9c48213377204519873SHIPMENT_DELIVEREDOK2350ACME2fa0af8dd88134eaf6867d912817eb9f7979dfac7028f8c7cc83931d682d4041The result equals notification.signature, so the flow starts. A label event comes without weight and carrier; because both paths end in ?, they are skipped:
{
"notification": {
"id": 48213377204519874,
"kind": "LABEL_VOIDED",
"signature": "a135da13804033a6e00ce843ce65446748d7b7f3d8a89da7088ae899e2750b5f"
},
"status": { "code": "OK" },
"shipment": { "reference": "ORD-2041" }
}whk_demo_7f3a9c48213377204519874LABEL_VOIDEDOKa135da13804033a6e00ce843ce65446748d7b7f3d8a89da7088ae899e2750b5fKey after the fields, reversed
Other senders append the key, sometimes reversed. With Secret position set to After the fields and Secret format set to Reversed, the same delivery event is hashed as:
48213377204519873SHIPMENT_DELIVEREDOK2350ACMEc9a3f7_omed_khw3ad92baeb0cd911bb6ec6f8a881fd5d31be44155f3b8551480345c581d79c16bWhen you connect a new sender, take one real request from its logs and recompute the checksum by hand as above. If it doesn't match, check the order of the fields, which ones are optional, and where and in which form the key is added.
A payload checksum has no timestamp, so it can't detect a replayed request. Make the flow safe to run twice (see Responses, retries and duplicates).
Filtering events
Senders often deliver every event type to the same URL. The Optional event filter is a JavaScript expression that decides whether a verified request starts the flow. When it returns false, the request is still answered with 200, but no run is created.
The filter can read:
state.body: the parsed JSON body, or the raw text whenRequest bodyis set toText (UTF-8).state.headers: forwarded request headers. None are forwarded unless the flow is defined in code withforwardHeaders.state.deliveryId: a unique id per request (for Stripe, the event id).state.receivedAt: when the request arrived, as an ISO timestamp.
["SHIPMENT_DELIVERED", "SHIPMENT_RETURNED"].includes(state.body.notification?.kind)state.body.type === "checkout.session.completed" && state.body.data.object.payment_status === "paid"Request body is JSON by default. Choose Text (UTF-8) for senders that post plain text; Stripe and payload checksums always need JSON. Requests can be up to 64 KiB.
Using the payload in steps
Steps find the request under the trigger's key. For a trigger with the key parcelUpdate, the state looks like this:
{
"parcelUpdate": {
"deliveryId": "0b6c1e52-4f0a-4f4e-9a59-2f1d3c7e8a10",
"receivedAt": "2026-11-17T09:41:12.512Z",
"headers": {},
"body": {
"notification": { "id": "48213377204519873", "kind": "SHIPMENT_DELIVERED", "signature": "2fa0af8d…" },
"status": { "code": "OK" },
"shipment": { "reference": "ORD-2041", "weight_grams": 2350, "carrier": "ACME" }
}
}
}An Update entry step can then find the order by state.parcelUpdate.body.shipment.reference and set its delivery status.
Large numbers arrive as text
Whole numbers above 9,007,199,254,740,991 can't be stored exactly as JavaScript numbers and would be rounded. The trigger keeps their exact digits and passes them as text: the notification.id above arrives as "48213377204519873". Compare such values as text, e.g. state.parcelUpdate.body.notification.id === "48213377204519873". Smaller numbers and decimals stay numbers.
Responses, retries and duplicates
The webhook URL answers with these status codes:
200: verified and queued, or verified and skipped by the event filter.400: the body is not valid JSON, or not a valid Stripe event.401: verification failed.404: the flow or trigger doesn't exist, or the flow is disabled.413: the request is larger than 64 KiB.503: a temporary problem, such as the secret not being available. Senders retry later.
200 confirms that the run was queued, not that it finished. The flow's runs show the result of each step.
Most senders retry until they get a success response, and some send the same event more than once. Design flows so that a repeated delivery does no harm:
- Look records up by the sender's own identifier, such as an order number or an event id, instead of creating a new record for every request.
- Store the latest status and never move it backwards, e.g. ignore a 'pending' update for an order that is already marked 'delivered'.
- Each request gets its own
deliveryId; only Stripe reuses its event id across retries.
Webhook triggers in code
When an assistant builds flows over the Turbofy MCP, webhook triggers are declared with flowBuilder.trigger.webhook. The parcel tracking trigger from above, plus an HMAC trigger:
triggers: {
parcelUpdate: flowBuilder.trigger.webhook({
verification: {
type: "payload-checksum",
secretId: "<secret-record-id>",
checksumField: "notification.signature",
fields: [
"notification.id",
"notification.kind",
"status.code",
"shipment.weight_grams?",
"shipment.carrier?",
],
secretPosition: "prepend", // "append" (default) | "prepend"
secretTransform: "none", // "none" (default) | "reverse"
},
condition: '["SHIPMENT_DELIVERED", "SHIPMENT_RETURNED"].includes(state.body.notification?.kind)',
}),
invoices: flowBuilder.trigger.webhook({
verification: {
type: "hmac-sha256",
secretId: "<secret-record-id>",
header: "x-signature",
prefix: "sha256=",
},
bodyFormat: "json",
forwardHeaders: ["x-request-id"],
}),
},secretIdis the id of a workspace secret, never the key itself.forwardHeaderspasses the listed lowercase headers to the flow. Authentication, cookie, API key and signature headers can't be forwarded.- Trigger keys may contain 1–128 letters, digits, hyphens or underscores; the key is part of the URL.
Run logs contain the full request body, including any personal data the sender includes. Turn a flow's debug logging off once it works.