Webhook URL triggers

Some services never let you subscribe to anything. They have one box, it says paste your webhook URL here, and that box is the whole integration. A Framer form. A Typeform. A Zapier or Make step. The cron job on a colleague's server. For those, the workflow hands you a URL and you go and paste it.

When to pick this, and when not to

A trigger has four shapes. A schedule runs the workflow on a clock. An event trigger has the assistant write the code that subscribes to a service for you. An email trigger watches a mailbox. A webhook URL is the fourth: the platform mints an address, and you are the one who tells the other system about it.

Pick the webhook URL when the other service has no API to subscribe against, when you hold no credential for it, or when the thing that should start the workflow is a script you control.

Prefer an event trigger when the service does have an API and you can connect it. A subscription the platform manages survives you forgetting which of four form builders you pasted something into, and it gets re-armed when the service drops it. A pasted URL has no such memory. It works until somebody deletes it in the other system, and nothing on our side can see that happen.

The assistant applies the same rule when it decides which one to offer you.

Getting the URL

Ask for it during the interview, or name a service whose integration is a paste-a-URL box, and the assistant sets the trigger up and shows you a card with the URL and a copy button. That happens in the first minutes of the conversation, long before there is anything to publish.

The URL never passes through the model. The assistant's tools get back a status line, and the card fetches the URL from the API and renders it in your browser. That is the same rule every credential in the product follows, applied here to the one credential the platform mints for you instead of taking from you.

The same URL sits in the workflow workspace under the Apps tab, in the Triggers section, so you can go back for it without reopening the conversation.

Paste it, then prove something arrives

Pasting is the easy half. The half that goes wrong is discovering three days later that the other service was never sending anything.

So a draft does not accept deliveries by default. While the workflow is a draft or paused, the URL answers the same 404 as a wrong secret, unless you open a listen window:

1. Open a listen window. It stays open for two minutes.
2. Go to the other system and make the event happen for real. Submit the form, press its test button, run the script.
3. The first delivery that lands is captured, and the window closes on it.

One window catches one delivery. Open another one and try again as often as you like. Both surfaces can do it, because you are in one or the other and rarely both: ask the assistant in the interview, or use listen, then run a test in the console's test run panel.

What the capture gives you

The delivery that lands is not just a green tick. Its payload goes into the workflow's payload library and is pinned as the example the workflow is built against. So:

• every step written after that is written against the fields the service really sent, rather than the fields the assistant expected it to send;
• a test run fires with that exact payload;
• the assistant can read it in the interview and ask you about the parts that are ambiguous.

That is the whole reason the listen window exists. A URL that answers 200 proves the URL works. A captured payload proves you know what is coming.

Going live

Publish arms it. Every delivery that arrives after that starts a run, with no window to open and nothing to press first.

The URL does not change when you publish. There is no test URL and no separate production URL, which is deliberate: two URLs is the most common way to break one of these, because the one already pasted into the other system is the one that stops working. The URL a workflow gets in its first minute is the URL it keeps for life.

Pausing takes it back to the draft behaviour. Publishing again rotates nothing, so a workflow whose URL lives in somebody else's console can be paused and re-published without a trip back to re-paste it.

The auth token

Beside the URL there is a second credential, the auth token. The URL secret authenticates the URL; the token authenticates the sender. They are two things rather than one so that a service demanding a signing secret can be handed the token while the URL stays exactly as pasted.

The platform generates a token for you, so the trigger is authenticated whether or not you make a decision about it. You can replace the value with one of your own, and when you do it goes from your keyboard to the API without passing through the assistant.

Three ways to present it, and which one you use depends on what the other service's form offers:

• A custom header. You name the header and the service sends the token as its value. The whole value has to match, exactly. Nothing is stripped off the front, so a service that sends Bearer abc needs Bearer abc as the token.
• HTTP basic auth. Username all-agents, password the token. The username is fixed and is not a secret. One less field is one less field to get wrong.
• An HMAC signing secret. For a service that signs its deliveries instead of sending a token, the token is the secret it signs with. The signature is checked on every request, not only on the first one.

A delivery that fails the check is refused with a 401 and counted, so a mistyped header name shows up on the trigger as a number rather than as silence.

What the workflow receives

A delivery arrives as an envelope rather than as a bare body, because plenty of these services put the thing you care about in a query string or a header:

Any method is accepted. A GET carrying everything in the query string works, a POST with a JSON body works, and a step can tell the two apart because method is right there in the envelope.

HEAD and OPTIONS are the exception. On a live URL they answer 200 and do nothing else: no run, no listen consumed. A service's "test connection" button usually probes with one of them, and a probe answered with a 404 reads as a broken URL. On a URL that is not live, they get the same 404 as everything else.

See trigger payloads for what a run then does with this.

The same delivery twice

One request is one run. Nothing on this path hashes the body to guess at duplicates, because a form submitted twice with the same answers is genuinely two submissions, and only the sender knows the difference between that and a retry.

If the service does send a delivery id, tell the assistant which header or field carries it. Two deliveries with the same id then become one run.

Regenerating

Regenerating is one deliberate action and it rotates both credentials together, the secret in the URL and the auth token. It closes any open listen window too.

It is the only thing that changes the URL, which means it breaks the URL everywhere you pasted it. Do it when the URL has leaked, and expect to go around the other systems afterwards with the new one.

What this will not do

• A browser cannot post to it. The route sends no CORS headers, and that is not an oversight waiting to be fixed. A URL a page can post to is a URL that anyone who views that page can post to, and the URL is the credential. Post from a server.
• One workflow, one URL. There is no second URL for the same workflow and no way to give two systems distinguishable addresses. If you need two, that is two workflows.
• Form-encoded bodies arrive as text. An application/x-www-form-urlencoded body is not split into fields. It lands in body as the string that was sent. Most of these services post JSON. If yours posts a form, parse it in a step.
• File attachments are not ingested. That limit is the same here as it is for every other trigger.
• A live workflow's deliveries cannot be captured through a listen window. Once the workflow is published a delivery is a run, and that run's payload is already in the Past tab of the payload library.