Fly.io Machine and Health Change Feed
Overview
The general app platform does not document a customer-configurable webhook subscription and signing surface, so this route uses supported change detection through Machines reads and state waits, health status, deployment evidence, and documented log shipping. Extension-provider machine-event webhooks are a separate partner-specific contract and are not assumed here.
Prerequisites
- Selected signal types, apps, regions, process groups, and service objectives
- Durable last-seen state, deduplication key, overlap policy, and sink acknowledgement
- Read-only token and redaction rules for Machine, health, release, and log fields
Instructions
Step 1: Choose supported signals
Use Machine list or get for inventory, the Machine wait endpoint for a known transition, health-check status for routing readiness, release evidence for deployments, and documented log shipping for application events.
Step 2: Snapshot the starting boundary
Record active Machine ID and instance version, lifecycle state, image, checks, regions, and the observation-window checkpoint before polling.
Step 3: Normalize change identity
Create a deterministic key from app, Machine, instance version, signal type, observed transition, and source timestamp. Preserve provider request or release lineage.
Step 4: Deduplicate before publishing
Compare with last-seen state and the sink acknowledgement store. Publish only changed, validated, redacted records and advance the checkpoint after acknowledgement.
Step 5: Detect gaps and stale monitors
Alert on missed polls, wait timeouts, health age, log-export lag, state discontinuities, and unknown instance replacement. Re-read authoritative state before replay.
Step 6: Reconcile downstream action
Operational events may recommend but must not automatically restart, scale, or delete resources without a separately approved control policy.
Authentication
Use a read-only organization token for monitoring where possible and send bearer credentials only to documented Fly.io endpoints. Keep log-export credentials separate. Do not invent a shared webhook secret or signature header for general Fly Apps.
Tool Discipline
Use Read and Grep to inspect application configuration, deployment evidence, provider documentation, fixtures, logs, schemas, and existing tests before proposing a change. Use Write or Edit only for an approved plan, configuration, implementation, test, or redacted receipt. Do not create, deploy, scale, restart, stop, suspend, destroy, rotate, revoke, expose, or migrate live Fly.io resources without explicit operator approval.
Output
- Signal catalog and checkpoint policy
- Normalized redacted changes with deterministic IDs and source lineage
- Lag, gap, deduplication, acknowledgement, and reconciliation receipt
Return the target organization, app, environment, region set, Machine or database identifiers, source-contract fingerprint, evidence, unresolved risks, rollback state, and final decision without exposing tokens, secrets, connection strings, or customer data.
Examples
A monitor records each Machine ID, active instance version, image, state, and health. After a deploy, it emits one change per replacement, waits for sink acknowledgement, advances state, and never claims that Fly.io delivered a signed webhook.
Error Handling
| Failure | Response |
|---|---|
| Wait endpoint times out | Read the current Machine and instance version, record an unknown or delayed transition, and avoid duplicate action. |
| Health timestamp is misunderstood | Treat last-updated as the last status change, not the most recent check execution. |
| Downstream acknowledgement is unknown | Replay the same deterministic record and let sink deduplication prevent duplicate effects. |