Webhooks

Webhooks push a signed copy of every control-layer state change to an endpoint you control. The one you actually need is action.requires_approval paired with approval.resolved: that pair is how an agent waits on a person without polling.

Ledger events are a separate subscription with a different registration endpoint and a different event set. See Ledger: webhooks. The signature scheme is identical, so one verification routine covers both.

Register an endpoint

Endpoints are per workspace and need the manage_policy capability.

curl -X POST https://api.kordio.io/control/v1/workspaces/$KORDIO_WORKSPACE/webhook_endpoints \
  -H "Authorization: Bearer $KORDIO_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/webhooks/kordio",
    "enabled_events": ["action.requires_approval", "approval.resolved", "budget.low"]
  }'

201 Created

{
  "data": {
    "id": "c93f7b21-4e08-4a56-b7d3-05e2a9c14f60",
    "url": "https://app.example.com/webhooks/kordio",
    "enabled_events": ["action.requires_approval", "approval.resolved", "budget.low"],
    "status": "active",
    "secret": "whsec_4bSFH1YTkjwsgiMrHMwWJfJTIzsov60WxxsziZAE",
    "created_at": "2026-08-04T09:30:00Z"
  }
}

secret is returned exactly once, at creation. Store it immediately. If you lose it, rotate the endpoint with POST /control/v1/workspaces/{slug}/webhook_endpoints/{id}/rotate, which mints a new one and stops the old one verifying immediately.

An empty enabled_events array subscribes to every event type, not none. Name the types you handle.

Event types

A payment fires both spellings. Anything whose action_type starts with payment. emits the payment.* event and its action.* equivalent, whichever endpoint booked it, so an endpoint subscribed to either name hears about it.

Type	Fires when
`action.requires_approval`	A rule held an action for a person. The one to subscribe to.
`action.completed`	An agent reported an authorized action succeeded.
`action.failed`	An agent reported it failed; the reservation is released.
`payment.requires_approval`	A payment is held for a person.
`payment.executed`	An agent reported an authorized payment went through.
`payment.failed`	A payment failed; the reservation is released.
`approval.resolved`	A person approved or denied. On the payment path the payload carries `resolution`.
`budget.low`	A budget dropped to 10% or less of its size. Only a completed payment fires it, never a completed action.
`spend_token.expired`	A spend token passed its expiry unused.

An unrecognised name in enabled_events is rejected with a 422 at registration. Never treat approval.resolved as permission on its own. It tells you a decision was made, not what it was, and an approved intent carries no cosignature. Read the outcome, and for anything that moves money verify the cosignature at the point of execution.

Delivery shape

{
  "id": "e0a4c72f-1b95-4d68-a3f0-7c25e91b4d38",
  "type": "action.requires_approval",
  "created_at": "2026-08-04T09:31:12Z",
  "data": { }
}

Header: Kordio-Signature: t=<unix>,v1=<hex>, an HMAC-SHA256 over <timestamp>.<raw_body> keyed by the endpoint secret.

Verify the signature

Handler

app.post(
  "/webhooks/kordio",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.headers["kordio-signature"] as string;
    if (!verifySignature(req.body.toString(), sig, process.env.KORDIO_WEBHOOK_SECRET!)) {
      return res.status(401).json({ error: "invalid signature" });
    }
    const event = JSON.parse(req.body.toString());
    if (event.type === "approval.resolved") {
      // resume the agent
    }
    res.json({ received: true });
  },
);

Respond and retry

A delivery succeeds on any 2xx. Anything else, including a timeout or a connection error, is retried with polynomial backoff for up to eight attempts, after which the delivery is marked failed with its last error recorded. The ledger API retries on a different schedule; if you point both at one handler, do not assume a shared budget. Return 2xx quickly and do heavy work asynchronously. Events carry stable ids, so treat handlers as at-least-once and deduplicate on the event id.

If you would rather poll

Everything a webhook reports is also readable. The audit trail is the durable version of the same story:

TRACE_ID="5e8c1a47-2b93-4d06-a7f1-9c3e05b8d24a"   # from decision.data.trace_id

curl "https://api.kordio.io/control/v1/workspaces/$KORDIO_WORKSPACE/audit_events?trace_id=$TRACE_ID" \
  -H "Authorization: Bearer $KORDIO_DASHBOARD_TOKEN"

Filtering by trace_id pulls one action’s whole history across authorization, approval and outcome. Every role can read it, including member.

Get started

Core concepts

Guides

Guarantees

Reference

Endpoints

Register an endpoint

Event types

Delivery shape

Verify the signature

Respond and retry

If you would rather poll

Next steps

Holding spend for a person

API reference

​Register an endpoint

​Event types

​Delivery shape

​Verify the signature

​Respond and retry

​If you would rather poll

​Next steps

Holding spend for a person

API reference

Register an endpoint

Event types

Delivery shape

Verify the signature

Respond and retry

If you would rather poll

Next steps