Webhooks deliver real-time event notifications to external systems via HTTP POST callbacks. Each subscription specifies a target URL, a set of event types to receive, and a shared secret for signature verification.
Event Types
Subscribe to specific categories or use the "*" wildcard for all events:
| Category | Events |
|---|
| Execution | run.started, run.completed, run.failed |
| Governance | approval.created, approval.resolved |
| Lifecycle | agent.deployed, agent.undeployed |
Delivery
Events are delivered with exponential backoff retry (3 attempts). Each delivery is tracked with status (success or failed), HTTP response code, and timing. Failed deliveries after 3 attempts are marked as permanently failed.
Subscription Lifecycle
| State | Description |
|---|
| active | Receiving events and creating deliveries for matching event types |
| paused | Temporarily stopped — no new deliveries. Can be paused manually or auto-paused after 10 consecutive failures. |
| resumed | Reactivated from paused state, failure counter reset |
| revoked | Permanently disabled. In-flight deliveries are skipped. |
Security
Every delivery includes an X-Forge-Signature header containing an HMAC-SHA256 signature computed with the subscription’s secret. Consumers should verify this signature before processing the payload. The X-Forge-Delivery header provides a unique ID for deduplication.
Subscription Fields
| Field | Description |
|---|
url | Endpoint URL that receives webhook payloads |
events | Event types to subscribe to (array or "*") |
secret | HMAC-SHA256 signing secret |
label | Human-readable identifier (optional) |
status | active, paused, or revoked |
createdAt | Subscription creation timestamp |
In Burgundy: Manage webhooks from Settings. → 
