Webhook triggers
A webhook trigger lets an external system start the workflow with an HTTP call. It is the right choice when something happens in a system you do not control and you want to react as it happens: an order confirmed in a marketplace, a file registered by a supplier portal, a status pushed by a payment provider.
The address is issued per trigger
The endpoint address is issued per trigger and shown on the trigger in Cockpit. Copy it from there and hand it to the calling system.
There is no address pattern to construct. You cannot derive the address from the workflow's name, the tenant, or the trigger's id, and creating a second webhook trigger gives you a second, different address — even on the same workflow. Installing a template that carries a webhook trigger issues a fresh address for your copy, so an address from someone else's screenshot is not yours.
Practically, that means the address is a piece of configuration you have to move by hand, once, from Cockpit into the calling system. Treat it as one: keep it wherever that system's configuration lives, and expect to re-copy it if the trigger is ever recreated.
Method matching
A webhook trigger declares the HTTP method it accepts — GET, POST, PUT, PATCH or DELETE, defaulting to POST. A call using any other method is rejected, with a response naming the method the endpoint expects. It does not start a run.
If a partner's system reports a 405, the method on the trigger and the method they are sending do not match; nothing else is wrong. Check the trigger first — it is a one-field fix, and it is the single most common false alarm on a new integration.
What the workflow sees
The request is turned into a payload with four parts:
| Expression | Value |
|---|---|
${{ trigger.payload.body }} | The request body — parsed when it is JSON or a form post, raw otherwise |
${{ trigger.payload.query }} | Query-string parameters |
${{ trigger.payload.headers }} | The request headers, with authentication headers removed |
${{ trigger.payload.method }} | The method the call used |
Authentication headers are stripped before the payload is built, so a workflow — and its run history — never carries the caller's credential. Do not design a flow that reads a token out of headers and forwards it; it will not be there.
Whether the caller waits
A webhook interacts with the workflow's execution_mode, and the default is not the same as it is for a run you start yourself:
async_only— the call is acknowledged immediately and the run continues in the background.sync_only— the caller waits for the result.caller_decides— the caller waits by default. This is the opposite of creating a run directly, which defaults to asynchronous.
A synchronous webhook is capped at 30 seconds. See Execution modes for what that means for a caller that retries.
Design the calling side for the mode you chose: a fire-and-forget caller against an asynchronous webhook never sees a workflow failure, so the failure has to be visible on your side — an error branch that notifies, or the run history.
Where to go next
- Execution modes — the synchronous cap, and the build gate a call passes through.
- Triggers — what all four types share.
- Expressions — reading the four payload parts into a node's config.
- Webhooks — the other direction: the platform calling your endpoint.