Triggers — webhooks and schedules
Start runs of a saved process from another system or on a cron — a URL that is its own credential, an optional HMAC signature, idempotent retries, and a schedule that fires each slot exactly once.
A process does not have to wait for someone to press Start. A trigger starts runs of one saved process by itself:
- a webhook gives another system (a claims portal, a CRM, a form) a URL to
POSTJSON to — each delivery starts a run; - a schedule starts a run at every slot of a cron expression, in a time zone you pick.
A trigger never signs a gate. It starts runs; they park at your gates like any other
run, and a person whose role allows it signs. Runs a trigger starts record
created_by: "trigger:<name>", and their run_started audit entry names the trigger.
Autonomy is the company's, not the caller's. A run a trigger starts follows the same
autonomy policy as one a person starts: the gate
resolver clears the reversible low- and medium-risk steps it would clear anyway — that is
your company's own configured policy, not a signature. A gate the policy parks for a human
waits for a person who signs it through the sign-off card (or Slack); no audit entry ever
records a gate signature in a trigger (trigger:<name>)'s name.
Only the published version runs
A trigger starts the process's published version (see
Publishing processes) — or the version it is pinned to
with draft_version, and only while that one is the published one. A trigger never starts a
draft, not even in shadow. While nothing is published, a webhook answers 409 with the
reason and a schedule keeps its slot and records the reason as last_error, retrying later;
the Triggers tab says so. You can create a trigger before publishing: it fires once a version
is published.
Who manages triggers
An owner or admin — in the admin, or from the API with their session — or an
API key with the triggers:manage scope. Every create, change, URL
rotation and delete is written to the audit chain in the same
transaction (trigger_created, trigger_changed, trigger_rotated, trigger_deleted),
without the URL or any secret.
In the admin, open Processes, select a saved process and switch to its Triggers tab. It lists each trigger with its URL prefix or cron, whether it is enabled, its next slot, when it last fired (with a link to that run) and its last error.
Webhooks
curl -s -X POST "$API/triggers" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "claims-intake",
"process_slug": "prior-auth",
"kind": "webhook",
"signing": true,
"input_mapping": {"member_id": "$.member.id", "procedure_code": "$.procedure"},
"idempotency_field": "$.event_id"
}'The 201 response carries url (https://app.minctrl.com/api/hooks/t/wh_…) and, because
signing is on, secret (whsec_…). Both are shown once. Minctrl keeps only the URL
token's SHA-256 and its first 6 characters (the list shows …/hooks/t/wh_AbC123…), and the
signing secret sealed (AES-256-GCM, bound to your company). Lost the URL? Rotate it (POST /triggers/{id}/rotate) — the old
one answers 404 from that moment. Lost the secret? Turn signing off and on again
(PATCH {"signing": true} returns a new one), or send your own with "secret": "…".
Delivering
Without signing, a delivery is a plain POST of JSON to the URL. With signing on, each
delivery carries a Minctrl-Signature header:
Minctrl-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>." + raw body)>Sign the exact bytes you send, with the current time. Minctrl refuses (401) a delivery
whose t is more than 5 minutes from its clock — in either direction — and refuses
(409, no run) a signature it already accepted, so a captured delivery cannot be replayed,
neither later nor inside those 5 minutes. To send an event again, sign it again (a new t);
with the same Idempotency-Key it then returns the first run. A delivery that started no run
(422, 503) may be retried as it was. Keep the sender's clock in sync (NTP). Several v1=
values are accepted (one must match), which lets a sender move to a new secret without a gap.
URL='https://app.minctrl.com/api/hooks/t/wh_…' # from the create response
SECRET='whsec_…' # from the create response
BODY='{"event_id":"evt_1042","member":{"id":"M-10293"},"procedure":"27447"}'
T=$(date +%s)
V1=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')
curl -s -X POST "$URL" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: evt_1042" \
-H "Minctrl-Signature: t=$T,v1=$V1" \
--data-binary "$BODY"
# {"run_id":"9b7c…","status":"awaiting_human"}import hashlib, hmac, json, time
import httpx
url, secret = "https://app.minctrl.com/api/hooks/t/wh_…", "whsec_…"
body = json.dumps({"event_id": "evt_1042", "member": {"id": "M-10293"}, "procedure": "27447"}).encode()
t = int(time.time())
v1 = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
r = httpx.post(url, content=body, headers={
"Content-Type": "application/json",
"Idempotency-Key": "evt_1042",
"Minctrl-Signature": f"t={t},v1={v1}",
})
print(r.status_code, r.json()) # 201 {'run_id': '9b7c…', 'status': 'awaiting_human'}The SDKs compute the header for you: minctrl.sign_delivery(secret, body) in Python,
await signDelivery(secret, body) from @minctrl/sdk in TypeScript.
- Inputs. Without
input_mapping, the JSON body (an object) is the run's inputs. With it, each input is the value at its JSONPath —$.a.b,$.list[0],$['odd key']; a missing one is422.fixed_inputswin under either: a body (or a mapped field) with the same name cannot override what the trigger pins. - Signature. With signing on, a missing header, a wrong
v1, a header withoutt, or atmore than 5 minutes old or ahead are all the same401—{"detail": "Invalid or missing Minctrl-Signature."}. A trigger created without a secret takes unsigned deliveries; turning signing on makes the signature required from then on. - Idempotency. Send
Idempotency-Key: <id>(or name a body field inidempotency_field): the same key within 24 hours returns the first run —200withIdempotent-Replayed: true— instead of starting another, also when two deliveries race. - Responses.
201{run_id, status}and nothing of the run's trace.404for an unknown, malformed or disabled URL alike.413above the body cap (256 KiB).422for a body that is not a JSON object, a missing mapped field, or a process that cannot run — the reason is not sent back; it is the trigger's last error on the Triggers tab.429above the rate limit.503when a run could not be started now: retry.
The URL is the credential, so Minctrl keeps it out of its request logs and error reports.
Schedules
curl -s -X POST "$API/triggers" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "nightly-reconcile",
"process_slug": "prior-auth",
"kind": "schedule",
"cron": "0 2 * * *",
"timezone": "Europe/Berlin",
"fixed_inputs": {"batch": "nightly"}
}'cron has five fields (minute hour day-of-month month day-of-week); timezone is an IANA
name (default UTC). The response's next_fire_at is the next slot, in UTC. A slot that
does not exist on a daylight-saving night moves to the next existing minute; a cron that can
never fire (0 0 31 2 *) is refused with 422.
What you can rely on:
- One slot, one run — with any number of API replicas. The slot is claimed and moved in the same database transaction that creates its run, so a second replica cannot fire it too.
- Missed slots fire once. After downtime, a schedule fires the slot it missed once and then waits for the next slot from now — a three-hour outage of a five-minute schedule is one run, not thirty-six.
- A slot whose run could not start stays where it is. If the process was deleted or is
not executable, no run starts, the slot does not move, and the reason is the trigger's last
error. It is retried every 5 minutes (
TRIGGER_RETRY_SECONDS) until it starts or you disable the trigger. - Disabled means no slot. Disabling clears
next_fire_at; enabling takes the next slot from now — the slots while it was off are not "missed".
Changing, rotating, deleting
| Call | What it does |
|---|---|
GET /triggers?process=<slug> | The company's triggers, or one process's. Never a URL or a secret. |
PATCH /triggers/{id} | Only the fields sent change: enabled, name, draft_version (null = the published version), fixed_inputs, a webhook's input_mapping / idempotency_field / signing / secret, a schedule's cron / timezone. |
POST /triggers/{id}/rotate | A webhook's new url, once; the old one stops. 409 for a schedule. |
DELETE /triggers/{id} | The URL answers 404, the schedule stops. Runs it started keep their record. |
Refusals: 403 for anyone but an owner, admin or a key with triggers:manage; 404 for an
unknown trigger or process (or one in another company); 409 for a name already taken in
the company; 422 for a bad cron, time zone or JSONPath, or a field of the other kind.
From the SDKs
import minctrl
client = minctrl.MinctrlClient("https://app.minctrl.com", api_key="mk_live_…") # triggers:manage
hook = client.triggers.create(name="claims-intake", process_slug="prior-auth",
kind="webhook", signing=True)
store(hook["url"], hook["secret"]) # shown once
client.triggers.update(hook["id"], enabled=False)import { createMinctrl } from "@minctrl/sdk";
const mc = createMinctrl({ baseUrl: "https://app.minctrl.com", apiKey: process.env.MINCTRL_API_KEY });
await mc.triggers.create({
name: "nightly-reconcile", process_slug: "prior-auth", kind: "schedule",
cron: "0 2 * * *", timezone: "Europe/Berlin", fixed_inputs: { batch: "nightly" },
});Operating it
| Variable | Default | Meaning |
|---|---|---|
TRIGGER_SWEEP_SECONDS | 15 | How often each API instance looks for due slots; 0 turns the sweeper off. |
TRIGGER_RETRY_SECONDS | 300 | How long a slot whose run could not start waits before the next attempt. |
TRIGGER_WEBHOOK_RATE_LIMIT | 60/minute | Deliveries per webhook URL. |
TRIGGER_WEBHOOK_IP_RATE_LIMIT | 300/minute | Deliveries per client address, to any URL. |
TRIGGER_WEBHOOK_MAX_BYTES | 262144 | Body cap; above it, 413. |
MINCTRL_SECRETS_KEY | derived from JWT_SECRET | The one key every stored credential is sealed with, signing secrets included. Set it explicitly, so rotating JWT_SECRET does not make them unreadable. |
TRIGGER_PUBLIC_BASE_URL | $APP_URL/api | The base the returned webhook url is built on. |
Compliance readiness (SOC 2, HIPAA)
See each SOC 2 and HIPAA Security Rule control with its live state computed from the product, export the evidence with the matrix filled in, run in PHI mode (no model text stored, run inputs purged after N days, every run view recorded), and confirm the quarterly access review.
Self-hosting — Kubernetes, Hetzner and the data region
Run Minctrl on your own infrastructure with the Helm chart or the Hetzner Terraform, keep its data in one region, and know exactly what is tested and what stays yours to do.