> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Signed workflow ingress

> Launch a workflow from an outside system with a capability URL: token minting and rotation, optional HMAC checks, schema and wrap input modes, idempotency, rate limits, and status codes.

**Ingress** lets an outside system start a workflow run by POSTing to a URL:

```
POST https://hooks.forge.gloo.com/api/v2/ingress/wht_<token>
```

The Console shows the URL on the hooks host when configured (`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`](https://docs.gloo.com/forge/reference/http-api/workflows) instead: it is authenticated, it is attributed to a named External Application, and it can ask for a completion callback.

> [!WARNING]
>
> A capability URL in a log file, a Slack paste, a screenshot, or a browser history is a **compromised trigger**. It cannot be revoked by disabling a user or an app — the only remedy is to rotate the token, which takes effect on the next request. Treat an exposed ingress URL exactly as you would treat a leaked API key.
>
> The token travels in the URL **path**, so anything that logs request URLs records it in full: the sender's own delivery logs, a proxy or API gateway in front of Forge, a CDN, a browser's history. Choose senders and intermediaries whose URL logs you control, and rotate if the URL turns up in one you do not.

## 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.

| | Capability URL alone | Capability URL + HMAC |
| - | - | - |
| Who can use it | Any sender that can POST to a URL | Senders that can compute an HMAC over the body: your own code (timestamped), or GitHub and Linear (body HMAC) |
| What a leaked URL costs you | Anyone holding it can start runs until you rotate | Nothing on its own — an attacker still needs the shared secret |
| Typical senders | Zapier, Make, vendor "notify URL" fields, internal cron | Your own services, scripts, and relays; GitHub and Linear webhooks |

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.

> [!TIP]
>
> When verification is off, the URL is the whole of your security. Keep the rate limit tight, keep the workflow's blast radius small, and rotate on any suspicion.

## 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](https://docs.gloo.com/forge/reference/http-api/workflows/createIngressTrigger.md). 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](#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](#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](#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**

> [!TIP]
>
> 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

| Property | Value |
| - | - |
| Shape | `wht_` + 32 CSPRNG bytes, base64url — 256 bits of entropy |
| Storage | Domain-separated SHA-256 only. The plaintext is never persisted. |
| Display | The console shows `wht_` + the first 8 characters, enough to tell two triggers apart and 208 bits short of guessing the rest. |
| Reveal | Once, at create or rotate. |

**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.

| | Timestamped (recommended) | Body HMAC |
| - | - | - |
| Signed bytes | `` `${t}.${rawBody}` `` | the raw body |
| Header value | `t=<unix-seconds>,v1=<hex>` | `sha256=<hex>` (GitHub) or bare `<hex>` (Linear) |
| Replay of a captured request | Refused once `t` is more than 300 seconds from Forge's clock | Verifies indefinitely; see below |
| Idempotency header | Optional | **Required** |
| For | Your own services, scripts, and relays | GitHub, Linear, and other senders that sign the body only |

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 is `t=<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:

```js theme={null}
import { createHmac } from "node:crypto";

const body = JSON.stringify({ issueId: "ENG-42" });
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac("sha256", process.env.FORGE_INGRESS_SECRET).update(`${t}.${body}`).digest("hex");

await fetch(process.env.FORGE_INGRESS_URL, {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Signature": `t=${t},v1=${v1}` },
  body,
});
```

Sign from a shell. The secret and the capability URL are both credentials, and any user on the same host can read a process's command-line arguments, so neither goes on a command line: the secret is read from the environment inside `python3`, and the URL reaches `curl` as a config file on stdin (`printf` is a shell builtin, so it starts no process):

```bash theme={null}
BODY='{"issueId":"ENG-42"}'
T=$(date +%s)
V1=$(printf '%s.%s' "$T" "$BODY" | python3 -c 'import hashlib, hmac, os, sys; print(hmac.new(os.environb[b"FORGE_INGRESS_SECRET"], sys.stdin.buffer.read(), hashlib.sha256).hexdigest())')
printf 'url = "%s"\n' "$FORGE_INGRESS_URL" | curl --config - -X POST \
  -H 'Content-Type: application/json' \
  -H "X-Signature: t=$T,v1=$V1" \
  --data-raw "$BODY"
```

Sign the exact bytes you send. Re-serializing the JSON between signing and sending (a different key order, added whitespace) changes the body and fails verification.

### Body HMAC (GitHub, Linear)

The header value is the hex HMAC-SHA256 of the raw body, either prefixed `sha256=` 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.

Use Body HMAC only where the sender cannot produce the timestamped form, and rotate the URL if a request may have been captured.

| Sender | Signature header | Idempotency header | Where to set the secret |
| - | - | - | - |
| GitHub | `X-Hub-Signature-256` (`sha256=<hex>`) | `X-GitHub-Delivery` | The webhook's **Secret** field; set **Content type** to `application/json` |
| Linear | `Linear-Signature` (bare `<hex>`) | `Linear-Delivery` | The webhook's signing secret, shown when you create it |

Set the trigger's input mode to `wrap` for both: their payload shape is theirs, not your workflow's.

> [!WARNING]
>
> Verification is **fail-closed**. If a configured verification cannot be evaluated — the secret cannot be decrypted, the header is absent, the value is malformed, the timestamp is outside the window — the request is rejected with `401`. It is never treated as "no verification configured". A signed trigger cannot silently degrade into an open one.

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 `429`s you cannot explain, check the invocations list for `401`s alongside them.

## Input modes

| Mode | What the workflow receives |
| - | - |
| `schema` | The parsed request body, directly, as the workflow's runtime arguments. The body must satisfy the workflow's declared input schema or the request is rejected `422`. |
| `wrap` | `{ [wrapKey]: <the whole parsed body> }`. `wrapKey` is required — there is no default, and a `wrap` trigger without one is refused at create. `body` is the conventional choice. |

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

Set **`dedupeHeader`** 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.

> [!NOTE]
>
> This per-trigger mechanism is the *only* deduplication ingress has. The platform-wide [`Idempotency-Key`](https://docs.gloo.com/forge/reference/idempotency) 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 gets `429` 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](https://docs.gloo.com/forge/run/email.md) 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

| Limit | Value |
| - | - |
| Request body | 512 KiB. Larger bodies are rejected `413` before the request touches the database. The body is stored as the run's input, and 512 KiB leaves room in the 1 MiB run document for everything stored beside it. |
| Rate | 60/min default, 1–600 configurable, burst of 10 |
| Active runs per trigger | 50 non-terminal runs |
| Idempotency window | 24 hours |
| Invocation-log retention | 7 days |
| Invocations returned per read | 20 |

## Status codes

> [!NOTE]
>
> Every rejection body is a **constant for its status code**. It never varies with the reason. See [Why the errors say nothing](#why-the-errors-say-nothing).

A rejection answers in the platform [error envelope](https://docs.gloo.com/forge/reference/errors.md#error-envelope): `{ "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.

| Status | Meaning |
| - | - |
| `202` | Accepted. Body is `{ runId }`. |
| `200` | Deduplicated. Body is `{ runId, deduplicated: true }` — the *original* run, nothing new started. |
| `400` | The body is not valid UTF-8. Settled in the HTTP layer; nothing is recorded. |
| `401` | Signature verification failed (missing, malformed, not the trigger's scheme, wrong, timestamp outside the 300-second window, or unevaluatable). |
| `403` | The launch permission gate refused the run — typically because the trigger declares a permission the ingress principal does not hold. Nothing was started; an operator has to change the trigger. |
| `404` | No such trigger. Also the answer for a malformed token and a rotated-away token. |
| `410` | The trigger is paused (by an operator, or automatically because its creator lost `workflows:manage` or the workflow was retired or trashed), or the workflow it points at is gone or retired. This URL used to work. |
| `413` | Body exceeds 512 KiB. |
| `422` | Body is not valid JSON, contains an object key Convex cannot store, or does not satisfy the workflow's input schema (`schema` mode). |
| `429` | Rate limit exceeded, or the trigger is at its active-run cap. Carries `Retry-After`. |
| `500` | An unexpected failure on Forge's side. Retryable; nothing was started. |
| `503` | Nothing was started, and the cause clears on Forge's side: the platform kill switch is engaged, the workflow is paused or has no published version, its input contract is unreadable, or the creator-authority check could not be decided. Back off and retry. |

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**. A `404` 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-budget `429`: 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 needs `workflows:read`. Retained 7 days, 20 rows per read.
* **The audit log**, for the same events with full governance context.

> [!WARNING]
>
> Two rejection classes never appear in the invocations list, because there is no trigger to attribute them to: a **`404`** where no trigger matched the token at all, and a **`400` / `413`** settled in the HTTP layer before the database is touched. If a sender reports a `404` and the list is empty, that is consistent — the token is wrong, not the configuration.

## 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:manage` at 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 reason `creator_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 paused `410`. 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 with `workflows:manage` at 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 gets `503`, is recorded with reason `creator_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 `503` and 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 holds `workflows:use`, `workflows:read` and `runs: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.

Every ingress-launched run is stamped so it is never an unnamed actor:

| Field | Value |
| - | - |
| `triggerSourceType` | `webhook` |
| `triggerSourceId` | The trigger id — the run is always traceable back to the URL that started it |
| `triggeredBy` | `external-app:<id>` for an app-owned trigger, `webhook-trigger:<id>` for an operator-owned one (launched as `system:webhook-ingress`) |

### FreshService Customer attribution

A platform administrator can map a FreshService Ticket Company name to an active Forge
Organization Customer through `customerOrganizations.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

> [accordion] 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](#body-hmac-github-linear) 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:
>
> | Setting | Value |
> | - | - |
> | Input mode | `wrap`, `wrapKey: body` — GitHub's payload shape is GitHub's, not your workflow's |
> | Verification | **On**, scheme **Body HMAC**, header `X-Hub-Signature-256`, a secret of at least 16 characters |
> | Dedupe header | `X-GitHub-Delivery` (required for Body HMAC) |
> | Rate | Match your merge rate, not the default. `10`/min is generous for most repos. |
>
> **In GitHub**, go to **Settings → Webhooks → Add webhook**:
>
> * **Payload URL** — the ingress URL
> * **Content type** — `application/json` (required; `x-www-form-urlencoded` will fail JSON parsing with `422`)
> * **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.
>
> If you need replay protection, put a relay you control between GitHub and Forge: it verifies GitHub's signature, then re-signs the same body in the timestamped format at send time, and the trigger uses the Timestamped scheme.
>
> Your workflow then reads the event out of the wrapped body — `body.action`, `body.pull_request.number`, and so on.
>
> > [!TIP]
> >
> > GitHub's **Recent Deliveries** tab shows `202` and the response body carries a `runId`.

> [accordion] 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](#body-hmac-github-linear) with `Linear-Delivery` as the idempotency header.
>
> **In Forge**:
>
> | Setting | Value |
> | - | - |
> | Input mode | `wrap`, `wrapKey: body` |
> | Verification | **On**, scheme **Body HMAC**, header `Linear-Signature`, Linear's signing secret |
> | Dedupe header | `Linear-Delivery` (required for Body HMAC) |
>
> **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`.
>
> > [!NOTE]
> >
> > 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](#body-hmac-github-linear). 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.

> [accordion] 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**:
>
> | Setting | Value |
> | - | - |
> | Input mode | `schema` if you shape the payload in the zap, `wrap` if you pass a third-party payload straight through |
> | Verification | **Off** — Zapier cannot sign |
> | Dedupe header | Set a custom header in the zap (e.g. `Idempotency-Key`) mapped to a stable id from the trigger step |
> | Rate | As low as the zap actually needs |
>
> **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 `schema` mode
>
> * **Headers** — add `Idempotency-Key` mapped to a stable id from the trigger step. Without it, a zap that Zapier retries will start a second run.
>
> > [!WARNING]
> >
> > An unsigned trigger means the URL alone starts runs. Store it in Zapier's field and nowhere else, keep the rate limit tight, and point it at a workflow whose worst-case run you are willing to have triggered by anyone who ever sees that URL. Rotate on any suspicion.

## Pause, resume, retire

* **Pause** stops runs. The trigger answers `410` and 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](#governance-and-attribution)).

An ingress trigger has no next-fire time and never enters the schedule evaluator's scan window. `ingress.status` is its liveness, not the `enabled` flag that a cron trigger uses.

## Related

* [Scheduling & Triggers](https://docs.gloo.com/forge/run/scheduling-and-triggers.md) — the cron/interval side of the same trigger model
* [Workflows HTTP API](https://docs.gloo.com/forge/reference/http-api/workflows) — the authenticated dispatch door, and the completion callback
* [Webhooks](https://docs.gloo.com/forge/run/webhooks.md) — the outbound direction: Forge notifying you
* [Trust Fabric in production](https://docs.gloo.com/forge/run/trust-fabric.md) — the gates a dispatched run passes
* [Emergency stops](https://docs.gloo.com/forge/run/trust-fabric.md#emergency-stops) — the platform stop that produces a `503` here
* [Observability](https://docs.gloo.com/forge/run/observability.md) — finding the runs an ingress trigger started


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.