hooks.forge.gloo.com in production); otherwise it uses the deployment’s own *.convex.site origin. The staging host hooks.forge.staging.gloo.us is pending DNS, certificate verification and activation. Until then, keep the staging deployment’s *.convex.site origin. The /v2/ingress/wht_<token> spelling reaches the same trigger, and previously issued URLs keep working.
There is no Authorization header. The URL is the credential. Anyone who can reach that URL can start that one workflow, and nothing else.
This exists because the systems that most want to start a workflow — a GitHub repository, a Linear workspace, a Zapier zap, a vendor’s “notify this URL” field — are systems you cannot teach to mint an OAuth token. Ingress is the door built for them. If your caller can hold a credential, use POST /api/v3/workflows/dispatch instead: it is authenticated, it is attributed to a named External Application, and it can ask for a completion callback.
The capability-URL tradeoff
Forge could have required an HMAC signature on every ingress request. It does not, and the reason is worth stating plainly rather than hiding.
Requiring HMAC would have made ingress unusable for the largest class of caller it exists to serve. So verification is per-trigger and opt-in: turn it on for every sender that can sign, and accept the capability-URL-only posture only where the sender genuinely cannot.
Set up an ingress trigger
1
Create the trigger on the workflow
Open the workflow in Forge Console (Production → Workflows → the workflow) and add an ingress trigger, or create one through the API with createIngressTrigger. Creating one requires
workflows:manage, and the caller is recorded as its creator — never a value the client supplies. A Personal key’s trigger belongs to its owner; an External App’s or platform API key’s belongs to the app or key. The API returns the token and URL once. The URL keeps working only while you still hold workflows:manage (see Governance and attribution). A workflow can carry an ingress trigger and a schedule at the same time — they are independent.2
Copy the URL now
The full token is shown exactly once, at create. Forge stores only a domain-separated SHA-256 of it and cannot recover the plaintext — not for you, not for support. If you dismiss the dialog without copying it, rotate and try again.
3
Pick an input mode
schema if the sender’s body already matches the workflow’s declared inputs. wrap if it does not — see Input modes.4
Turn on verification if the sender can sign
Pick a signing scheme, then give Forge the header name the sender uses and the shared secret (minimum 16 characters). Use Timestamped for senders whose signing code you control; use Body HMAC for GitHub and Linear — see HMAC verification.
5
Set the rate limit to something you can defend
The default is 60 requests per minute. A trigger that should fire on merges to
main does not need 60/min — lower it.6
Send one real request and read the invocations list
The trigger’s recent-invocations list shows a
202 with a run id, and the run appears under Observe → Runs. Its triggerSourceType is webhook.Tokens and rotation
Rotation is immediate and total. There is no grace window and no two-token overlap: the moment you rotate, the old URL returns
404 and the new one works. Update the sender first, then rotate, and expect a gap if you get the order wrong.
Rotating is also the only revocation mechanism. Pausing (below) stops runs but leaves the token valid — a paused trigger answers 410, which tells a prober the URL is real. If the token is believed exposed, rotate; do not merely pause.
HMAC verification
When configured, the trigger verifies an HMAC-SHA256 keyed by a shared secret you and the sender both hold. Each trigger has one signing scheme, chosen when you configure verification. The scheme belongs to the trigger, not the request: a timestamped trigger refuses a body-only signature even when that signature is correct.
Common to both schemes:
- Mode:
hmac_sha256. - Header: you choose the name. Matching is case-insensitive.
- Secret: minimum 16 characters. Stored encrypted, and never returned by any read.
- Comparison is constant-time. Anything that does not parse as the trigger’s scheme is rejected.
Timestamped
The header value ist=<unix-seconds>,v1=<hex>, where v1 is the hex HMAC-SHA256 of the string `${t}.${rawBody}`: the timestamp exactly as sent, a literal ., then the body bytes exactly as sent. It must contain exactly one t and one v1, and no other parts.
t must be within 300 seconds of Forge’s clock, in either direction. Sign each request (and each retry) at send time, and keep the sender’s clock synchronized.
Binding the timestamp into the signature limits how long a captured request can be replayed. A copy cannot be re-sent later with a fresh timestamp, because changing the timestamp invalidates the signature, so it stops verifying once its original timestamp falls outside the window. Inside the window a copy still verifies. A dedupeHeader stops an honest duplicate in that window, but not an attacker: the dedupe header is not signed, so a copy can carry a new value.
Sign from Node:
python3, and the URL reaches curl as a config file on stdin (printf is a shell builtin, so it starts no process):
Body HMAC (GitHub, Linear)
The header value is the hex HMAC-SHA256 of the raw body, either prefixedsha256= or bare. That is what GitHub and Linear send, so they verify without a relay.
A body-only signature carries no time, so a captured request verifies indefinitely. Forge therefore refuses a body-HMAC trigger with no idempotency header: create and update fail with workflowTriggers/ingress-body-hmac-needs-dedupe, and so does clearing the idempotency header while the scheme is Body HMAC. The idempotency header is a limit on honest retries, not replay protection:
- An exact copy (same body, same delivery id) inside 24 hours returns the original run instead of starting a new one.
- An exact copy older than 24 hours starts a new run.
- The delivery id is not signed. Anyone holding a captured request and the URL can re-send it with a new delivery id at any time, and it starts a new run. They cannot change the body.
Set the trigger’s input mode to
wrap for both: their payload shape is theirs, not your workflow’s.
Signature checking runs after the rate-limit budget is consumed. That ordering is deliberate — it keeps a signature flood from being a free way to make Forge do cryptography — but it has a consequence worth knowing: a burst of unsigned junk still spends the trigger’s rate budget, so legitimate traffic arriving at the same time can be rate-limited. If you see 429s you cannot explain, check the invocations list for 401s alongside them.
Input modes
An empty body is treated as
{}. In both modes, a body containing an object key Convex cannot store — an empty key, a key starting with $, a key longer than 1024 characters, or a key with a non-printable or non-ASCII character, at any depth — is rejected 422 before any run is started.
Use schema when you control the sender and can shape its payload to the workflow’s contract. Use wrap for third-party senders whose payload shape is theirs, not yours — the workflow then declares a single object-typed input and does its own extraction. wrap is the right default for GitHub, Linear, and Zapier.
Idempotency
SetdedupeHeader to the name of a header the sender uses as a unique event id — X-GitHub-Delivery, Linear-Delivery, or your own Idempotency-Key.
When set, a repeated value within 24 hours returns 200 with { runId, deduplicated: true } carrying the original run’s id. No second run is started. A sender that retries because it did not see your 202 converges on the same run instead of doubling your work.
Outside the 24-hour window, or with no dedupeHeader configured, every request that clears the other checks starts a run.
This per-trigger mechanism is the only deduplication ingress has. The platform-wide
Idempotency-Key header that covers the other mutating /api/v3/* and /api/v2/* routes deliberately does not apply to POST /api/v2/ingress/*: ingress is unauthenticated by design — the capability URL is the secret — so there is no External Application principal to scope a key to. Configure dedupeHeader instead.Rate limits
Each trigger has a token bucket. It refills continuously at the configured rate — default 60 requests/minute, configurable from 1 to 600 — and holds at most 10 tokens (or the per-minute rate, if that is lower). A quiet trigger can absorb a burst of 10 requests at once; after that, requests are admitted at the refill rate. There is no window boundary to straddle: in any 60 seconds a trigger admits at most its rate plus its burst. A request over the budget gets429 with a Retry-After header giving the seconds until a token is available. A refused request spends nothing, so a sender that keeps retrying gets exactly the refill rate.
Active-run cap. A trigger may have at most 50 runs that have not finished (running, paused, or cancelling). While it is at the cap, new requests get 429 with Retry-After: 30. The cap applies to email routes too. The rate limit bounds how fast a leaked URL can start runs; the cap bounds how many can be alive at once, which matters most for long workflows and ones that pause for a person.
Above 600 per minute, a webhook is the wrong shape — put a queue in front and dispatch in batches through the authenticated API. A trigger saved with a higher rate before the ceiling was lowered is limited to 600.
Unknown tokens. Requests whose token matches no trigger share one deployment-wide budget of 120 per minute, spread across several counters so a flood of guesses does not queue behind a single record. Every guess still gets the same 404. Past that budget the guesses cost Forge no writes at all, and the server log records a sample of them rather than one line each.
Limits
Status codes
Every rejection body is a constant for its status code. It never varies with the reason. See Why the errors say nothing.
{ "error": { "code", "message", "docUrl" }, "meta": { "requestId" } }, with the request id also in the X-Request-Id header. A 403 the launch permission gate recorded also names its error.decisionId. Only meta.requestId changes from one rejection to the next.
Checks run in this order, and the first failure wins: token lookup → rate budget → paused → creator authority (operator-owned triggers) → signature → idempotency → kill switch → active-run cap → JSON parse and input validation → launch. The token lookup and rate budget run in their own transaction ahead of the rest. The cap is checked in the same transaction that starts the run, so simultaneous requests cannot push a trigger past it, and a repeated
dedupeHeader value still gets its original run back while the trigger is at the cap.
Why the errors say nothing
The endpoint is reachable by anyone on the internet who guesses a URL, so the response is the attack surface. A404 that distinguished “malformed token” from “unknown token” from “deleted workflow” would be a free oracle for a prober. So it does not: every rejection carries a fixed body for its status, and the status itself is the most a sender learns.
The real reason is recorded — it is just not shown to the sender. Look for it in:
- The trigger’s recent-invocations list in Forge Console. Every invocation that matched a trigger records its outcome, status code, and a human-readable reason (
"signature verification failed","per-minute rate budget exhausted","active-run cap reached (50 non-terminal runs)","input validation failed: missing required field issueId","creator_authority_lost: the creator no longer holds workflows:manage"). The exception is the rate-budget429: once a trigger is over budget, only the first such rejection in each one-minute window is recorded, so a flood cannot grow the log. Reading it needsworkflows:read. Retained 7 days, 20 rows per read. - The audit log, for the same events with full governance context.
Governance and attribution
Ingress is not a governance bypass, and it is also not a place where the whole gate engine runs at the door. Precisely:- At the door, before the signature is checked: for an operator-owned trigger, Forge re-checks that its creator still holds
workflows:manageat both org units creating it required: the workflow’s home and the trigger’s own org unit, the unit its runs are recorded in (a grant at the unit, at one of its ancestors, or at the platform covers it). A person’s worker seat and person must be active, and their current role grants must give the key; an External App or platform API key that created it must still be enabled (or unrevoked) and its own grants must give the key. If not, or if the workflow was deleted, the trigger pauses itself, the invocation is recorded with reasoncreator_authority_lost: …(creator_authority_lost: trigger org unit (<unit id>): …when only the trigger’s own org unit was lost), and the request gets the paused410. A URL therefore never outlives its creator’s authority. Resuming it does not change its creator, so it pauses again on the next request until someone withworkflows:manageat both recreates it. If the check cannot be decided (the workflow’s home is missing or cannot be resolved, the trigger’s own org unit cannot be resolved and the creator holds no platform grant, the creator’s role grants are too many to read in full, or their person record’s merge history is corrupt), that request gets503, is recorded with reasoncreator_authority_indeterminate: …, and the trigger stays active. - At the door, before any run row exists: the platform kill switch is evaluated, through the same canonical gate every other dispatch runner uses as its first check. If it is engaged, the request gets
503and nothing is created. - At launch: the run is launched by a principal the permission gate can resolve. An operator-owned trigger launches as the registered system principal
system:webhook-ingress, which holdsworkflows:use,workflows:readandruns:read— the same set the cron scheduler holds. The sender is never the principal: it is whoever holds the URL. An app-owned trigger launches as its External Application. - Inside the orchestrator’s per-node preflight: the per-agent budget, run cost cap, and policy gates bind — exactly as they do for every other workflow-launch path (the console, the authenticated API, the cron scheduler). Ingress gets the same pipeline those do, plus a stronger front door.
FreshService Customer attribution
A platform administrator can map a FreshService Ticket Company name to an active Forge Organization Customer throughcustomerOrganizations.upsertMapping. The Customer must
have a unique, active Customer–Organization link. A platform administrator can then enable
customerAttribution: { source: "freshservice_company", inputField: "companyName" } on an
operator-owned ingress trigger with schema input mode and HMAC verification. The incoming
companyName is matched only after the signature succeeds; clientName is not used. Missing,
ambiguous or stale mappings launch the workflow without a Customer ID. A matched run stores
both its Customer ID and an immutable signed FreshService attribution marker. The agent reads
Customer knowledge only for a run carrying that marker and webhook source identity while its
Customer Organization remains active. Later edits or pauses to the trigger do not change what
was verified when the run started. A generic webhook or API-launched run cannot acquire Customer
knowledge by supplying a customerId.
Recipes
GitHub — run a workflow on push or pull request
GitHub — run a workflow on push or pull request
GitHub signs the body (
X-Hub-Signature-256: sha256=<hex>) and sends a per-delivery id, so use the Body HMAC scheme with X-GitHub-Delivery as the idempotency header. The signature carries no timestamp, so read the replay limits in that section.In Forge, create the ingress trigger with:In GitHub, go to Settings → Webhooks → Add webhook:
- Payload URL — the ingress URL
- Content type —
application/json(required;x-www-form-urlencodedwill fail JSON parsing with422) - Secret — the same shared secret you gave Forge
- Events — select only the ones you want. “Send me everything” will exhaust your rate limit on a busy repo.
body.action, body.pull_request.number, and so on.GitHub’s Recent Deliveries tab shows
202 and the response body carries a runId.Linear — run a workflow on issue changes
Linear — run a workflow on issue changes
Linear signs the body (
Linear-Signature: <hex>) and sends a per-delivery id, so use the Body HMAC scheme with Linear-Delivery as the idempotency header.In Forge:In Linear, go to Settings → API → Webhooks → New webhook, paste the ingress URL, and select the resource types you care about (
Issue, Comment, …). Copy the webhook’s signing secret into the Forge trigger.Linear’s payload carries action (create / update / remove), type, and data. Under wrap your workflow sees them at body.action, body.type, body.data.Linear puts a
webhookTimestamp field in the body for receivers to check. Forge does not read it, so a captured Linear request can be replayed as described under Body HMAC. A workflow that must refuse stale events can compare body.webhookTimestamp to the current time itself. For replay protection at the door, relay through a service that verifies Linear’s signature and re-signs in the timestamped format.Zapier — run a workflow from any zap
Zapier — run a workflow from any zap
Zapier’s Webhooks by Zapier → POST action cannot compute an HMAC over the body. This is the case ingress exists for, and it is the one where the URL is your whole security boundary.In Forge:
In Zapier, add a Webhooks by Zapier → POST action:
- URL — the ingress URL
- Payload Type —
json - Data — the fields your workflow declares, if you are using
schemamode - Headers — add
Idempotency-Keymapped to a stable id from the trigger step. Without it, a zap that Zapier retries will start a second run.
Pause, resume, retire
- Pause stops runs. The trigger answers
410and the token stays valid. Use it for a maintenance window. - Resume puts it back to
202. - Rotate invalidates the URL. Use it for exposure, not for maintenance.
- Retiring or trashing the workflow pauses every capability URL on it, so they answer
410. Un-retiring or restoring the workflow does not resume them — resume each one deliberately. - Losing the creator’s authority pauses the trigger on its next request (see Governance and attribution).
ingress.status is its liveness, not the enabled flag that a cron trigger uses.
Related
- Scheduling & Triggers — the cron/interval side of the same trigger model
- Workflows HTTP API — the authenticated dispatch door, and the completion callback
- Webhooks — the outbound direction: Forge notifying you
- Trust Fabric in production — the gates a dispatched run passes
- Emergency stops — the platform stop that produces a
503here - Observability — finding the runs an ingress trigger started

