Event types & payloads

This is the catalog of events managed.dev emits. Every event shares one envelope; only the data payload differs by type. Subscribe an endpoint to the events you’ll act on, then verify and dedupe each delivery as described in the overview.

The common envelope

Every webhook body has the same outer shape. type selects the event and data carries the type-specific payload. Deduplication happens on the Forge-Delivery-Id request header, which stays stable across retries and replays — see best practices.

Common event envelope

{
  "id": "evt_01J9...",                 // the event id — stable across redeliveries
  "type": "deploy.completed",          // selects the payload shape in data
  "site_id": "site_01J7...",           // null for account/team-level events
  "env_id": "env_01J8...",             // null when not environment-scoped
  "created_at": "2026-06-23T18:05:02.118Z",
  "data": { /* type-specific payload */ }
}

Payloads are additive within an API version — ignore fields you don’t recognize rather than failing on them.

The machine-readable catalog

Don’t hard-code the list below. GET /v1/webhook-endpoints/event-types (webhooks:read) returns the live catalog — every subscribable type with its category, title, and severity — so a subscription picker or config validator always reflects the real, current set:

Fetch the event-type catalog

mf webhooks event-types

One catalog entry

{
  "type": "deploy.failed",
  "category": "deploy",
  "title": "Deployment failed",
  "severity": "error"
}

Categories double as subscription selectors: an endpoint subscribed to "category:security" receives every security type, including ones added to the category later. The full reference table — including which types ring the in-app bell and which send email — lives at event types.

Event catalog

Every type below is customer-visible and subscribable. Severity is the catalog default; vulnerability.matched and observability.alert set it per event from the underlying finding.

Category	Event type	Severity	Fires when
build	build.completed	info	A build produces a signed, content-addressed artifact.
build	build.failed	error	A build fails before producing an artifact.
deploy	deploy.completed	info	A deployment finishes and the environment serves the new release.
deploy	deploy.failed	error	A deployment can’t complete; the environment stays on its prior release.
backup	snapshot.completed	info	A backup finishes; data carries the new snapshot_id.
backup	snapshot.restored	info	A snapshot restore completes on an environment.
env	env.created	info	A new environment is provisioned.
env	env.create_failed	error	Environment provisioning fails.
env	env.destroyed	info	An environment is destroyed.
env	env.refreshed	info	An environment is re-seeded from production.
env	env.reset	info	An environment is reset.
job	job.succeeded	info	Any async job reaches succeeded.
job	job.failed	error	Any async job reaches failed.
observability	observability.alert	warning	A site health rule transitions into alerting.
observability	observability.resolved	info	An alerting rule recovers.
security	malware.scanned	info	A malware scan completes.
security	malware.detected	critical	A scan finds and quarantines malicious files.
security	vulnerability.matched	critical	A known CVE newly matches an installed component.
security	security.key_created	warning	An API key is created.
security	security.key_revoked	warning	An API key is revoked.
security	security.member_role_changed	warning	A team member’s role changes.
security	security.member_removed	warning	A member is removed from a team.
security	security.team_deleted	warning	A team is deleted.
site	site.created	info	A site is created.
site	site.deleted	warning	A site is deleted.
site	site.transferred	warning	Site ownership moves to another team or account.
team	team.member_added	info	A member joins a team.
team	team.invite_created	info	A team invite is created.

Events drive notifications too

The same catalog powers in-app notifications and email: each type carries flags for whether it rings the dashboard bell and whether it sends an email (failures, security, and critical alerts do; routine successes stay quiet). Per-category email preferences live at GET/PUT /v1/notification-preferences. A few operator-only types — host.offline, host.recovered, malware.quarantine_failed — route to the platform ops channel and are never delivered to customer webhooks.

Tip

job.succeeded and job.failed are the workhorses. Most mutations are asynchronous and return a job; subscribing to these two events means you never have to poll a job to completion. The higher-level types (deploy.completed, snapshot.completed, …) fire for the same terminal jobs — subscribe at whichever granularity fits your handler.

Example payloads

Job-derived events — deploys, builds, backups, environment lifecycle, and the generic job.* pair — carry the job that produced them, so your handler can fetch the full job envelope for detail:

deploy.completed — data payload

{
  "job_id": "job_01J9...",
  "job_type": "deployment.deploy"
}

snapshot.completed — data payload

{
  "job_id": "job_01J9...",
  "job_type": "backup.create",
  "snapshot_id": "snap_01J9..."
}

Security events carry the finding. malware.detected reports what a ClamAV scan found and quarantined:

malware.detected — data payload

{
  "count": 2,
  "paths": [
    "wp-content/uploads/2026/06/payload.php",
    "wp-content/uploads/2026/06/dropper.php"
  ],
  "signature": "PHP.Backdoor.Agent",
  "quarantine_failed": false
}

Treat security events as the highest priority

malware.detected and vulnerability.matched should route to your fastest channel. Pair them with the malware-scanning and blocks data, and use the security resource API to pull detection detail and drive remediation.

Next steps

Event-types referenceThe full table — every type with severity, bell, and email flags.

Webhooks overviewCreate endpoints, subscribe to events, and replay deliveries.

Verifying signaturesValidate the Forge-Signature header before trusting a payload.

Async jobsThe job envelope behind job.succeeded and job.failed.