feat: Webhook triggers for agent schedules (WEBHOOK-001)

[vybe]

Summary

Add webhook URL endpoints that trigger agent schedule executions from external systems. Each schedule can optionally expose a unique webhook URL with an embedded HMAC signature and expiration date, allowing external services (CI/CD, form submissions, CRMs, monitoring alerts) to initiate agent work without API authentication.

Motivation

Currently agents can only be triggered via: UI chat, cron schedules, MCP tools, or Slack. There's no way for arbitrary external systems to trigger agent work via a simple HTTP POST. Webhooks are the universal integration pattern for this.

Design

Webhook URL Format

POST /api/webhooks/{schedule_id}/{signature}

• signature = HMAC-SHA256(schedule_id + expiration, secret_key), base64url-encoded
• URL is self-contained — no auth header needed
• Optional expiration date embedded in the signature payload

Schedule Integration

• Each schedule gets an optional "webhook trigger" toggle
• When enabled, generates a unique webhook URL with configurable expiration (default: 90 days, or no expiry)
• Calling the webhook triggers the schedule exactly once (same as manual trigger)
• The schedule's message is used as the task prompt (webhook payload can optionally override/append context)
• Respects existing execution slot limits and queueing

Webhook Payload (optional body)

{
  "context": "Additional context appended to the schedule message",
  "metadata": { "source": "github", "event": "push" }
}

• context is appended to the schedule's message as additional input
• metadata is stored on the execution record for traceability

Security

• HMAC-SHA256 signature prevents URL guessing/tampering
• Expiration date prevents stale URLs from being used indefinitely
• Rate limiting per webhook URL (e.g., 10 calls/minute)
• Webhook URLs can be regenerated (invalidates old URL)
• Execution is logged with triggered_by: "webhook" for audit trail

API Endpoints

Method	Path	Auth	Description
POST	/api/webhooks/{schedule_id}/{signature}	None (signature)	Trigger execution
POST	/api/agents/{name}/schedules/{id}/webhook	JWT	Generate/regenerate webhook URL
DELETE	/api/agents/{name}/schedules/{id}/webhook	JWT	Revoke webhook URL
GET	/api/agents/{name}/schedules/{id}/webhook	JWT	Get webhook URL and status

Database

Add columns to agent_schedules:

• webhook_secret — per-schedule HMAC secret
• webhook_expires_at — optional expiration timestamp
• webhook_enabled — toggle

UI

• Webhook URL section in schedule detail/edit panel
• Copy-to-clipboard button for the URL
• Expiration date picker
• Regenerate/revoke buttons

Acceptance Criteria

• Schedule can generate a webhook URL with HMAC signature
• POST to webhook URL triggers schedule execution
• Optional expiration date is enforced
• Webhook payload context is appended to schedule message
• Rate limiting prevents abuse
• URL can be regenerated (old URL stops working)
• triggered_by: "webhook" appears in execution records
• UI shows webhook URL with copy button and expiration controls

[vybe]

Paused pending PROCESS-ENGINE-DECISION (2026-04-20)

Per orchestration simplification re-plan. The "reuse process-engine triggers vs. parallel agent-scoped surface" decision depends on whether the process engine stays at all — that question is getting resolved as part of Tier 2.5 (see PROCESS-ENGINE-DECISION issue).

If process engine is folded into TaskExecutionService or deleted, the answer to this issue changes materially:

• If engine stays and handlers fold through TES → reuse process-engine triggers (as previously recommended in the plan).
• If engine deleted → ship an agent-scoped webhook surface, but a much smaller one than previously sketched (since no BPMN layer exists).

Pausing until PROCESS-ENGINE-DECISION resolves so we don't design for a surface that's about to change shape.

See docs/planning/ORCHESTRATION_RELIABILITY_2026-04.md — Tier 2 (marked paused) and Tier 2.5.

[vybe]

Implemented and merged to dev via PR #484. See feature flow at docs/memory/feature-flows/webhook-triggers.md.