Guides
Webhooks
Hear about your runs and approvals the moment they happen, and let your own systems start work. Every delivery is signed, retried and kept.
Events
Add a webhook in the console (Settings, Webhooks) or with POST /v1/webhooks, choosing the events it receives, or * for all of them:
run.finished,run.failed,run.stopped: a run ended, with its result or why it failed.approval.waiting: an action waits for a person.approval.decided: a person approved or rejected it, or it expired.
An event is queued in the same moment as the change it reports, so none is lost and none is sent for a change that did not happen. A payload carries what happened, never a tool call's input.
{
"id": "evt_run_0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40.finished",
"type": "run.finished",
"created_at": "2026-11-12T10:00:00.000Z",
"data": {
"run": {
"id": "0b7c5f2e-4c1a-4f0e-9d2b-6a8e3f1c9d40", "state": "finished", "agent_id": "8f3a6d21-7e4b-4c90-a5d2-1b6e9c0f7a35",
"model": "claude-sonnet-5", "num_turns": 4, "cost_usd": "0.031200",
"created_at": "2026-11-12T09:59:41.000Z", "started_at": "2026-11-12T09:59:42.000Z", "finished_at": "2026-11-12T10:00:00.000Z",
"failure_reason": null, "result": "Three invoices are overdue; the reminders are drafted for your approval."
}
}
}Checking a signature
Deliveries follow the Standard Webhooks specification. Each carries webhook-id (the event's id: the same on a retry or a replay, so you can ignore a repeat), webhook-timestamp and webhook-signature: v1, and the base64 HMAC-SHA256 of id, timestamp and the raw body, joined by dots, keyed by your secret. Check it against the raw body before you parse it, and refuse a timestamp more than five minutes off. While a secret is being rotated, the header carries two signatures for 24 hours; either one matching is enough.
import { createHmac, timingSafeEqual } from 'node:crypto';
// secret: the whsec_ value shown when you added the webhook.
export function verify(secret, headers, rawBody) {
const id = headers['webhook-id'];
const ts = headers['webhook-timestamp'];
const sigs = (headers['webhook-signature'] ?? '').split(' ');
if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const want = createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest();
return sigs.some((s) => {
if (!s.startsWith('v1,')) return false;
const got = Buffer.from(s.slice(3), 'base64');
return got.length === want.length && timingSafeEqual(got, want);
});
}import base64, hashlib, hmac, time
def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
msg_id, ts = headers.get("webhook-id"), headers.get("webhook-timestamp")
if not msg_id or not ts or abs(time.time() - int(ts)) > 300:
return False
key = base64.b64decode(secret.removeprefix("whsec_"))
want = hmac.new(key, f"{msg_id}.{ts}.".encode() + raw_body, hashlib.sha256).digest()
return any(
s.startswith("v1,") and hmac.compare_digest(base64.b64decode(s[3:]), want)
for s in headers.get("webhook-signature", "").split(" ")
)Retries, the log and replay
Answer with any 2xx within 10 seconds. Anything else is tried again after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, 6 hours and 12 hours, then marked failed. A 410 Gone turns the webhook off at once, and one whose last 20 deliveries all failed over more than a day is turned off too, with the reason shown.
Every delivery and every attempt is kept for 30 days: the payload, the status your endpoint answered, how long it took and the start of its answer. Open them in the console or with GET /v1/webhooks/:id/deliveries, and send any one again with POST /v1/webhooks/deliveries/:id/replay. Send a test from the console or POST /v1/webhooks/:id/test.
We send only to public https addresses. A private, loopback or cloud metadata address is refused when we send.
Triggers: start a task from your systems
A trigger gives one agent an address, https://api.rykon.ai/v1/hooks/<id>, and a secret. A call signed the same way as our deliveries starts a run of that agent with the trigger's task, your request's body in place of {{payload}} as content to read, never instructions to follow. The samewebhook-id twice starts one run. Every limit, pause, kill switch and approval applies as to any run, and a trigger takes up to 60 calls a minute. The answer is 202 with the run's id.
body='{"order": 1042, "email": "ada@example.com"}'
id="msg_$(date +%s)"; ts=$(date +%s)
sig=$(printf '%s' "$id.$ts.$body" | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$(printf '%s' "${SECRET#whsec_}" | base64 -d | xxd -p -c 256)" -binary | base64)
curl -X POST "$TRIGGER_URL" -H "content-type: application/json" \
-H "webhook-id: $id" -H "webhook-timestamp: $ts" -H "webhook-signature: v1,$sig" -d "$body"