Skip to main content
An automation is a workflow in a HERO project: something happens, and HERO does something in response. Most start from a change in your workspace — a row is added, a document is signed. This page covers the other way in: your service posts data, and a workflow runs with it. Any automation can be started this way. There is no trigger to add and nothing to switch on beyond the credential you use.

​
Two ways in

Webhook

For another service calling HERO. Authenticated by a secret that belongs to one automation, so the caller needs no HERO account.

API

For your own code. Authenticated by your personal token, so the run records who started it.

​
Webhook

Find the URL and generate the secret in the automation’s Trigger reference panel. The secret is shown once — only a hash is stored, so it cannot be recovered later, but it can be rotated at any time. Generating that secret is what allows webhook calls. Rotating it invalidates every caller using the old one; there is no separate switch to turn off.
The secret may be sent as X-Hero-Webhook-Secret or as Authorization: Bearer whsec_…, whichever your service can set.

​
API

The API runs the automation as its owner, not as you — so it can do whatever the owner could, with the owner’s AI credit. Because of that it takes edit access to the automation’s project: a token that can only read it is refused with 403.

​
What you can post

Any JSON body, up to 1 MB. An object or an array both work — a service that batches events into a list is a normal caller, not a special case. A body larger than the limit is refused with 413 rather than truncated, so a run never acts on half a message.
Both surfaces accept 200 requests per minute. Above that you get 429.

​
Reading the fields you sent

Anywhere a step takes text — an email body, an AI instruction, a cell value — write a hero:trigger/payload token and HERO substitutes what you posted. Put a dot after payload, then use slashes to go deeper: The @ menu offers what you posted as a starting point and inserts @[what you posted](hero:trigger/payload), which resolves to the whole body. Add the path yourself to narrow it to one field — the label is only what you read, the part in brackets is what resolves.
Only the first separator is a dot. hero:trigger/payload.user.name is not a path and resolves to nothing — use hero:trigger/payload.user/name.
A field you did not send resolves to an empty string, not to the token itself. A step that depends on one will act on a blank rather than fail loudly, so branch on it if it matters:

​
Routing one endpoint to different work

Services that send several kinds of event usually post a type field. Start one automation, then split on that field with a path step — one branch per event kind, and a fallback for everything you have not handled yet. That keeps one URL and one secret per integration, rather than an automation for every message type your service might send.

​
Checking what arrived

Open the automation and expand a run. A run started by a post shows What was posted — the exact body HERO received. Reach for it first when a step produces nothing: almost always the field is nested a level deeper than the token assumed, or the service names it something else. The run cannot tell you that a field was missing, because a missing field and an empty one resolve the same way.

​
Responses

​
Not sending the same thing twice

Send an Idempotency-Key header — on either endpoint — and a repeat of the same key returns the original run instead of starting another:
The response is 200 with replayed: true, so a service that retries on timeout cannot run your workflow twice. Use the sending service’s own event id.