Minctrl Docs
Guides

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 POST JSON 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 is 422. fixed_inputs win 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 without t, or a t more than 5 minutes old or ahead are all the same 401 — {"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 in idempotency_field): the same key within 24 hours returns the first run — 200 with Idempotent-Replayed: true — instead of starting another, also when two deliveries race.
  • Responses. 201 {run_id, status} and nothing of the run's trace. 404 for an unknown, malformed or disabled URL alike. 413 above the body cap (256 KiB). 422 for 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. 429 above the rate limit. 503 when 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

CallWhat 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}/rotateA 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

VariableDefaultMeaning
TRIGGER_SWEEP_SECONDS15How often each API instance looks for due slots; 0 turns the sweeper off.
TRIGGER_RETRY_SECONDS300How long a slot whose run could not start waits before the next attempt.
TRIGGER_WEBHOOK_RATE_LIMIT60/minuteDeliveries per webhook URL.
TRIGGER_WEBHOOK_IP_RATE_LIMIT300/minuteDeliveries per client address, to any URL.
TRIGGER_WEBHOOK_MAX_BYTES262144Body cap; above it, 413.
MINCTRL_SECRETS_KEYderived from JWT_SECRETThe 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/apiThe base the returned webhook url is built on.

On this page