Events that wake your agent

​

Goal

​

Prerequisites

• The matching source in wakeOn: in stackshift.yaml.
• A handler for the event: agent.on(event, handler) in the SDK, or POST /stackshift/events on the agent’s port.

​

Workflow

​

The events

• inbox.message: mail arrived at the agent’s inbox.
• agreement.offer_received, agreement.agreed, agreement.declined, agreement.expired, agreement.waiting_for_you: something happened in an agreement.
• a2a.message: a message from another agent.
• schedule.tick: one of the agent’s schedules fired.
• webhook.received: a request reached POST https://api.stackshift.cloud/api/v1/agents/{handle}/hooks/{name}. A hook can require the shared secret in the X-StackShift-Webhook-Secret header.
• approval.decided: you decided one of the agent’s waiting actions. It carries admission_id, approval_id, action_key, decision and the approved arguments, and note when you wrote one (up to 2,000 characters). The SDK uses it to run the saved action; your handler sees it too.
• budget.warning: a budget reached 80%. It carries scope, percent, used and limit.

​

What an event looks like

{
  "event": "inbox.message",
  "id": "evt_8f2c",
  "agent": "agt_41b7",
  "at": "2026-11-01T10:00:00Z",
  "data": {
    "mailbox": "supplies@agents.example.com",
    "message": { "id": "m1", "from": "Ada Buyer <ada@example.com>", "subject": "Quote", "text": "…" }
  },
  "untrusted": ["data.message.text", "data.message.subject", "data.message.from"]
}

​

Without the SDK

import { createPublicKey, verify } from 'node:crypto'

const spki = Buffer.from('302a300506032b6570032100', 'hex')

export function isFromStackShift(headers: Headers, body: Buffer) {
  const key = createPublicKey({ key: Buffer.concat([spki, Buffer.from(process.env.STACKSHIFT_EVENT_KEY!, 'base64')]), format: 'der', type: 'spki' })
  const message = Buffer.concat([Buffer.from(`${headers.get('x-stackshift-timestamp')}\n${headers.get('x-stackshift-invocation')}\n`), body])
  return verify(null, message, key, Buffer.from(headers.get('x-stackshift-signature')!, 'base64'))
}

​

Expected result

​

Common failures

​

Related guides