Build an execution connector#
An execution connector is the bridge between "the agent decided" and "the work happened". It is an HTTPS endpoint you control. Remindify sends a signed request; your endpoint does the work and returns a proof reference.
Connect one#
- Deploy an HTTPS endpoint that accepts
POST. - Open the agent's passport in Agents.
- Paste the URL and save. Remindify shows a signing secret once.
- Store the secret in your executor's environment.
- Reconnecting rotates the secret and invalidates the old one.
Executor URLs must resolve to a public address. The resolved address is pinned for the send, so a second DNS answer cannot redirect the call inward. Redirects are refused. For local development, set EXECUTOR_ALLOW_LOCAL=1 and use http://localhost:<port>.
The request#
POST /your/execute
x-remindify-event: obligation.execute
x-remindify-run: run_ab12cd3
x-remindify-timestamp: 1761600000000
x-remindify-signature: sha256=<hmac>
x-remindify-attempt: 1
content-type: application/jsonThe body:
{
"event": "obligation.execute",
"run_id": "run_ab12cd3",
"issued_at": "2026-10-28T09:00:00.000Z",
"workspace": { "id": "ws_5f2c...", "name": "Exopya Studio" },
"agent": { "id": "ag_ledger", "name": "Ledger", "handle": "ledger" },
"obligation": {
"id": "ob_rent",
"title": "Pay rent",
"provider": "Selam Properties",
"amount": 750,
"currency": "USD",
"due_at": "2026-11-01T09:00:00.000Z",
"autonomy": "autopilot"
},
"action": "Executed the obligation",
"detail": "Pay $750 to Selam Properties using the verified account, then archive the receipt."
}Verify the signature#
The signature is HMAC-SHA256(secret, "<timestamp>.<raw body>"), hex encoded. Verify against the raw body, before JSON parsing.
Node#
import { createHmac, timingSafeEqual } from "node:crypto";
import { readFileSync } from "node:fs";
const secret = process.env.REMINDIFY_EXECUTOR_SECRET;
const rawBody = readFileSync(0, "utf8"); // or collect the request stream
const expected = createHmac("sha256", secret)
.update(`${process.env.TIMESTAMP}.${rawBody}`)
.digest("hex");
const given = String(process.env.SIGNATURE || "").replace(/^sha256=/, "");
const ok = given.length === expected.length &&
timingSafeEqual(Buffer.from(given), Buffer.from(expected));
if (!ok) {
console.error("bad signature");
process.exit(401);
}Express#
app.post("/your/execute", express.raw({ type: "application/json" }), (req, res) => {
const timestamp = req.get("x-remindify-timestamp");
const given = String(req.get("x-remindify-signature") || "").replace(/^sha256=/, "");
const expected = createHmac("sha256", process.env.REMINDIFY_EXECUTOR_SECRET)
.update(`${timestamp}.${req.body.toString("utf8")}`)
.digest("hex");
const ok = given.length === expected.length &&
timingSafeEqual(Buffer.from(given), Buffer.from(expected));
if (!ok) return res.status(401).json({ error: "bad_signature" });
const event = JSON.parse(req.body.toString("utf8"));
// do the work
res.json({ proof: "transfer_ref_88213" });
});Python#
import hashlib, hmac, os
expected = hmac.new(
os.environ["REMINDIFY_EXECUTOR_SECRET"].encode(),
f"{timestamp}.{raw_body}".encode(),
hashlib.sha256,
).hexdigest()
ok = hmac.compare_digest(expected, given.removeprefix("sha256="))Respond with proof#
Return any 2xx. Include a proof reference:
{ "proof": "transfer_ref_88213" }receipt_url is also accepted. The reference is filed on the obligation and in the run history.
| Response | What Remindify records |
|---|---|
2xx with proof or receipt_url |
Run done; proof filed. |
2xx without either |
Run done with connector_<status> as the proof, so the gap is visible. |
408, 429, 5xx, timeout, network error |
Transient: retried inline, then queued. |
Other 4xx |
Permanent failure; no retry. |
2xx but malformed JSON |
Treated as a failure; nothing is marked complete. |
Never return 2xx before the work is durably done. A green response is a promise that the proof exists.
Retries and duplicate delivery#
- Inline: up to three attempts with exponential backoff (
EXECUTOR_ATTEMPTS,EXECUTOR_RETRY_BASE_MS,EXECUTOR_TIMEOUT_MS). - After inline failures: the job moves to a durable outbox. It keeps the original
run_id, retries with backoff up toOUTBOX_MAX_ATTEMPTS, and completes the obligation when your endpoint finally answers. - Delivery is at-least-once. A crash can land between claiming a job and recording the result.
- Dedupe on
x-remindify-run. Every attempt for the same logical execution carries the same run id, even when the timestamp and signature are fresh. - The local server sweeps the outbox every 30 seconds. Serverless deployments call
GETorPOST /api/cron/outboxwithAuthorization: Bearer $OUTBOX_SECRET. - A permanently failed or exhausted job stays visible with its last error.
Example idempotency check:
const seen = new Set(); // use a database in production
if (seen.has(req.get("x-remindify-run"))) {
return res.json({ proof: "already_done" });
}Reject stale requests#
The timestamp is milliseconds since the epoch. Reject anything older than a few minutes to limit replay:
const age = Date.now() - Number(req.get("x-remindify-timestamp"));
if (!Number.isFinite(age) || age > 5 * 60 * 1000) {
return res.status(401).json({ error: "stale" });
}A replay inside the window is still possible, so pair this with run-id deduplication.
Local testing#
EXECUTOR_ALLOW_LOCAL=1 npm run devRun your executor on http://localhost:9099, connect it in the passport, and set an obligation to approve or autopilot. Watch the run in the passport. Disconnect the executor to return the agent to draft-only.
Do not#
- Do not execute from inside the signature check. Verify first, then act.
- Do not put the signing secret in the URL query string.
- Do not return a proof reference that is not checkable by a human.
- Do not treat the obligation id as authorization for unrelated work. The connector decides what this agent may do.