Agent Triggers
A helpdesk opens a ticket, a form is submitted, an order is paid: the system it happened in can start the work itself instead of something polling for it. A trigger is a URL that system calls with the event as its body. The server checks the signature, maps the body into the input of an agent or workflow, and starts a durable run at once.
1Make a trigger#
Open Admin > Connect > Triggers and choose New trigger:
| Field | What it sets |
|---|---|
| Id | The last part of the URL: /lmkit/v1/triggers/{id} |
| Starts | A published agent, or a published workflow |
| Input | The run's input. {{body}} is the body as sent; {{body.ticket.subject}} or {{body.items[0].sku}} reads a value inside a JSON body |
| Variables | For a workflow: values its steps read as vars.<name>, each a template like the input |
| Runs as | The API key whose grants, owner and quotas the runs use |
Saving shows the URL and the signing secret once. Give both to the sending system. New secret replaces it; deliveries signed with the old one are refused from then on.
2Sign each delivery#
A delivery carries no API key. It carries two headers:
| Header | Value |
|---|---|
X-LMKit-Timestamp |
The time of sending, in Unix seconds |
X-LMKit-Signature |
sha256= and the hex HMAC-SHA256 of {timestamp}.{body} under the secret |
body='{"id":"T-1042","subject":"Printer jams","customer":{"name":"Dana"}}'
ts=$(date +%s)
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$TRIGGER_SECRET" | sed 's/^.* //')
curl -X POST https://your-server/lmkit/v1/triggers/ticket-created \
-H "Content-Type: application/json" -H "X-LMKit-Timestamp: $ts" \
-H "X-LMKit-Signature: sha256=$sig" -H "Idempotency-Key: evt_8812" -d "$body"
import hashlib, hmac, json, time, urllib.request
body = json.dumps({"id": "T-1042", "subject": "Printer jams"}).encode()
ts = str(int(time.time()))
sig = hmac.new(SECRET.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
request = urllib.request.Request(URL, data=body, method="POST", headers={
"Content-Type": "application/json", "X-LMKit-Timestamp": ts,
"X-LMKit-Signature": "sha256=" + sig, "Idempotency-Key": "evt_8812"})
print(urllib.request.urlopen(request).read())
Sign the exact bytes you send. The answer is 202 with run_id; follow the run with
GET /lmkit/v1/runs/{id} under the trigger's key, or on Admin > Operate > Runs.
3What is refused#
| Answer | Why |
|---|---|
401 |
No signature, a signature that does not match, or a timestamp more than five minutes from the server's clock |
403 |
The trigger's API key was revoked, deleted or expired |
404 |
No such trigger, or it is disabled |
409 |
The agent or workflow it starts is no longer published |
413 |
A body over 1 MB |
429 |
The trigger's key is past one of its quotas (Retry-After says when to retry) |
4Retries never start a run twice#
A sender that did not see the answer sends again. Send an Idempotency-Key naming the event: any
delivery with the same key answers 200 with the run the first one started and
"duplicate": true, for a day. Without the header, the same signed request sent again (same
timestamp, same body) is recognized the same way. Every node of a farm shares the record, so a retry
that reaches another node is recognized too.
Test on a trigger's row sends a signed event from the panel and shows the raw exchange: the request as sent and the trigger's answer, with a link to the run it started.