Start runs from another system
This guide is for developers and authors connecting another system to Lainstack. The other system sends an HTTP request, and each request starts a run. The Webhook trigger reference lists every output; Triggers explains how webhooks behave.
1. Add the Webhook trigger
Section titled “1. Add the Webhook trigger”Create an automation (see Build your first automation) and add Webhook from the block library. Its settings panel calls it API Invoke.
2. Set the URL
Section titled “2. Set the URL”In the trigger’s Webhook section:
- Endpoint key is the last part of the URL, for example
orders-from-partner-x. Use 6 to 120 letters, digits,-or_. - Webhook URL shows the full address with a copy button. It changes when you change the endpoint key.
- Webhook enabled turns the endpoint off without unpublishing the automation.
3. Choose how callers prove who they are
Section titled “3. Choose how callers prove who they are”Pick an Authentication mode:
| Mode | The caller sends |
|---|---|
| API key | The secret in the x-automation-api-key header, or as Authorization: Bearer <secret>. |
| Signed (HMAC SHA-256) | x-automation-timestamp and x-automation-signature: sha256=<hex>, where the signature is HMAC SHA-256 of <timestamp>.<raw body> with the secret. Requests older than 5 minutes are refused, so a captured request cannot be replayed. Recommended for partners. |
| No authentication | Nothing. Anyone who knows the URL can start a run, so use it only for public automations that change nothing important. |
For the first two, the Webhook secret is generated when the automation is saved and shown once. Copy it then and store it in the calling system. After that the panel only says Secret configured. Regenerate makes a new secret and the old one stops working.
Allowed source IPs limits callers to the addresses you list, one IP or CIDR range per line. Leave it empty to accept any address.
4. Check what callers send
Section titled “4. Check what callers send”Under Input validation, choose:
- No validation to accept any payload as it is.
- Fields to describe the JSON body field by field, or import a JSON Schema file to fill them in. A body that is not an object, such as a list, arrives as a field named
value. Requests that do not match are rejected and start no run. - XSD (XML) to do the same for XML bodies.
With a schema, the body’s fields appear as typed inputs (payload.data.<field>) that later blocks can map with @. Files sent as multipart parts arrive as attachments.
5. Test with a sample
Section titled “5. Test with a sample”Open the trigger’s Samples tab and fill in its fields with values like the ones the caller will send. They save as you leave each field. Build the rest of the automation against it, then click Run draft and choose Pinned sample. No request is needed.
6. Publish and call it
Section titled “6. Publish and call it”The endpoint is live only once the automation is published. Click Publish, then send a request. The trigger settings show a Request example for the chosen mode, for example:
curl -X POST '<webhook URL>' \ -H 'x-automation-api-key: <secret>' \ -H 'content-type: application/json' \ -d '{"orderId":"A-1001"}'Lainstack answers 202 Accepted with an event ID as soon as the run is queued.
The caller does not get the run’s result; if it needs one, have the automation send it back, for example with HTTP Request. If the same delivery arrives twice, the second answer is 200 with deduped and no second run starts.
Requests that fail authentication, come from an address that is not allowed, or do not match the schema are refused and start no run. A caller that sends too much too fast gets 429.
7. Watch the runs
Section titled “7. Watch the runs”Open Runs and filter to the automation to see each request’s run. To start the run again with a payload a caller really sent, open the trigger’s Samples tab and use Capture from last run. See Debug a failed run.