data payload carries, and the subscriptions it is useful for. The envelope (the wrapping id, type, created_at, workspace, version, data) is the same across all of them — see Webhooks overview for the wrapper. This page only documents the type value and the contents of data.
How event types are named
Every type is dotted:<resource>.<verb>. The resource is the thing the event is about. The verb is the state transition that fired the event. Subscribe to a specific type to receive only that one, or to a prefix (pages.*) to receive every event on the resource.
pages.*
pages.published
Fires when a page reacheslive status after a successful build. Subscribe to this if you mirror page metadata into another system (a CMS index, a search service, a CDN cache invalidator).
pages.rolled_back
Fires when a page is rolled back to an earlier version. The payload names both versions so a downstream consumer can reconcile.forms.*
forms.submitted
Fires once per submission to a published Form block. The payload includes the field values exactly as the end user entered them — verify the signature before trusting any field as user identity.submitter_ip is the originating client IP after trusted-proxy unwrapping. It is null when the form was submitted from a trusted internal source (an agent run, a Builder preview).
deployments.*
deployments.completed
Fires when a deployment reaches a terminal status —live, failed, or cancelled. One event per terminal transition.
payments.*
These fire on the end-user payment lifecycle that the collectPayment capability initiated. Use them to mark orders paid, grant access, or trigger fulfillment.
payments.succeeded
The payment cleared. This is the event you wire fulfillment to.payments.failed
The payment did not clear.failure_code is one of the standard provider codes (card_declined, insufficient_funds, expired_card, etc.).
payments.refunded
Issued on a refund — full or partial.amount is the refunded amount in the original currency’s minor unit.
subscriptions.*
Fires on end-user subscription state changes for monetized workspaces. The provider-driven lifecycle states are normalized to platform terms so a workspace subscribed to this stream does not need provider-specific glue.
subscriptions.created
A new subscription record exists. Status isactive or trialing.
subscriptions.updated
The plan, price, or quantity changed. The payload carriesbefore and after snapshots of the relevant fields.
subscriptions.canceled
The subscription was cancelled.cancel_at distinguishes immediate cancellation from end-of-period cancellation.
agents.*
Fires on the lifecycle of agent runs. Use these if you want to mirror run history into a dashboard or alert when a run fails.
agents.run_started
A run was opened. Carries the trigger reason and the agent id.agents.run_completed
A run reachedcompleted status. The payload includes summary statistics — duration, steps executed, capabilities dispatched.
agents.run_failed
A run failed. The payload includes the failing step and an error envelope matching the API error shape.approvals.*
approvals.pending
A run hit a gate and an approval record was created. Subscribe to this when you route reviews into a Slack or email channel.approvals.decided
An operator approved or denied a pending record.decision is approved or denied; reviewer is the principal that decided.
approvals.expired
A pending record reached the workspace’s approval TTL without a decision. The parent run was stopped.workflows.*
Mirror events to agents.* but for workflow runs. Useful when a workflow is fired by something other than an agent — a direct API call, a block binding — and you need lifecycle visibility into the run without polling.
workflows.run_startedworkflows.run_completedworkflows.run_failed
domains.*
domains.verified
A custom domain transitioned toverified after a successful DNS check.
domains.failed
A verification attempt found the DNS record missing or incorrect. The payload includes the expected and observed values.domains.detached
A previously-verified domain was detached from the workspace.secrets.*
These carry metadata only. No event ever includes a secret value, the encrypted blob, or anything derivable from the value.
secrets.set
A value was written (created or overwritten). Payload:name, purpose, set_by, updated_at.
secrets.rotated
A rotation completed. Payload:name, rotated_by, rotation_trigger (one of scheduled, manual, upstream_forced).
secrets.deleted
A secret was deleted. Payload:name, deleted_by.
workspace.*
workspace.billing_state_changed
A workspace transitioned between billing states —active → past_due, past_due → canceled, canceled → active, and so on. Subscribe to this if you mirror customer state into a CRM.
workspace.plan_changed
The workspace plan was swapped. Payload includesfrom_plan_id and to_plan_id.
workspace.locked
The workspace was placed on a compliance or billing hold. Capability dispatch is paused until the hold is resolved.Subscribing to a subset
Webhook subscriptions take a list of event types. Use either a fully-qualifiedpages.published or a prefix pages.* to receive everything on a resource. There is no global * — you list the families you care about.
Versioning
The envelopeversion field starts at 1. New event families ship without bumping the version. The version increments only when the envelope shape itself changes; the platform commits to delivering both shapes during a deprecation window when that happens.
Inside a data payload, fields are additive. New optional fields may appear on existing event types without notice. Existing fields are not renamed or repurposed; if a payload needs a breaking change, a new event type ships alongside the old one and the old one is deprecated.