DocsBuildAPI ReferenceSDK Reference

Webhooks & event triggers

Agents participate in the same event bus as external HTTPS subscribers. Declare on[] in your manifest, implement event_trigger capabilities, and emit follow-on events with ctx.events.emit.

Manifest: on[] patterns

Each entry registers an agent_trigger subscription for your org. The platform matches inbound and outbound events (after ingest or emit), then queues a task for your agent with the event payload. Use dot-notation types; trailing .* matches a prefix family.

yaml
# fragment: manifest.yaml
name: invoice-processor
version: "1.0.0"
org_id: did:org:acme


capabilities:
  - capability: event_trigger
    evidence: []
  - capability: event_trigger:billing.invoice.paid
    evidence: []


# Wake the agent when an event matches (pattern from deployment registration)
on:
  - event: billing.invoice.paid
    description: Process paid invoices within the org
  - event: billing.invoice.*
    description: Wildcard: any invoice.* subtype

Ensure event_trigger and event_trigger:<event_type> capabilities are declared so HumanOS can authorize the run.

Handler input

For trigger runs, the worker passes structured input including event_id, event_type, payload, org_did, and verification hints. Treat it like any other task, then emit downstream events as needed.

typescript
import type { AgentHandler } from '@human/agent-sdk';


export const handler: AgentHandler = async (ctx, input) => {
  // Your handler receives event_trigger input when subscribed via on[]
  const eventType = (input as { event_type?: string }).event_type;
  const payload = (input as { payload?: Record<string, unknown> }).payload ?? {};


  await ctx.events.emit('invoice.processed', {
    ...payload,
    processed_at: new Date().toISOString(),
  });


  return { ok: true, event_type: eventType };
};

Local testing

  • Run the API and use POST /v1/events/ingest or POST /v1/events/emit with a delegation that covers human_api:events:write.
  • Confirm your agent appears in Command Plane → Webhooks (agent-trigger rows show target URL as empty; delivery logs apply to external subscriptions only).
  • Watch async executions and provenance for the triggered run.

See also