asyncapi: 2.6.0 info: title: Fly.io Extensions Webhook Events description: >- The Fly.io Extensions webhook system delivers real-time event notifications in both directions between Fly.io and extension providers. Fly.io sends CloudEvents-format payloads to the provider's registered endpoint URL when machine lifecycle events occur that are relevant to an extension resource. Extension providers send lifecycle status updates back to Fly.io at the platform webhook endpoint when asynchronously provisioned resources become ready, are updated, or are deleted. All webhook payloads in both directions are signed using HMAC-SHA256 with separate shared secrets, allowing each party to verify authenticity before processing events. version: '1.0' contact: name: Fly.io Extensions Program url: https://fly.io/docs/reference/extensions_api/ termsOfService: https://fly.io/legal/terms-of-service/ externalDocs: description: Fly.io Extensions API Documentation url: https://fly.io/docs/reference/extensions_api/ servers: flyio: url: 'https://api.fly.io' protocol: https description: >- Fly.io platform server that receives webhook notifications from extension providers and sends CloudEvents to provider webhook endpoints. security: - webhookHmac: [] provider: url: 'https://{provider_base_url}' protocol: https description: >- Provider-hosted server that receives CloudEvent webhook notifications from Fly.io about machine and account lifecycle events relevant to their extension resources. variables: provider_base_url: description: The base URL of the extension provider's webhook receiver. channels: /api/hooks/extensions/{provider_name}: description: >- Fly.io platform endpoint that receives webhook notifications from extension providers about resource lifecycle changes. Providers post to this channel to notify Fly.io when asynchronously provisioned resources become ready, when resource configuration changes, or when resources are removed. parameters: provider_name: description: The registered slug identifier for the extension provider. schema: type: string publish: operationId: receiveProviderWebhook summary: Receive a lifecycle webhook from an extension provider description: >- Fly.io receives this message from an extension provider when a resource lifecycle event occurs. The payload is signed with the provider's HMAC-SHA256 webhook signing secret. Fly.io verifies the signature before updating the extension resource state on the platform. message: oneOf: - $ref: '#/components/messages/ResourceCreated' - $ref: '#/components/messages/ResourceUpdated' - $ref: '#/components/messages/ResourceDeleted' /extensions/events: description: >- Provider-hosted endpoint that receives CloudEvents-format webhook notifications from Fly.io about machine and account lifecycle events. Providers register this endpoint with Fly.io and must verify the HMAC-SHA256 signature on all incoming payloads. subscribe: operationId: receiveFlyioMachineEvent summary: Receive a machine or account event from Fly.io description: >- Fly.io sends this CloudEvent to the provider's registered events endpoint when a machine lifecycle event or account change occurs that is relevant to the provider's extension resources. The payload is signed using the webhook signing secret issued to the provider. message: oneOf: - $ref: '#/components/messages/MachineStarted' - $ref: '#/components/messages/MachineStopped' - $ref: '#/components/messages/MachineDestroyed' - $ref: '#/components/messages/AccountChanged' components: securitySchemes: webhookHmac: type: httpApiKey name: X-Fly-Signature in: header description: >- HMAC-SHA256 signature computed over the raw request body using the shared webhook signing secret. Recipients must recompute this signature and compare it to the header value to verify the payload is authentic and has not been tampered with. messages: ResourceCreated: name: ResourceCreated title: Extension Resource Created summary: Notifies Fly.io that an extension resource has been provisioned description: >- Sent by an extension provider to confirm that an asynchronously provisioned extension resource is now ready. The payload includes the resource ID and the environment variable configuration to inject into the user's Fly App. contentType: application/json headers: type: object properties: X-Fly-Signature: type: string description: HMAC-SHA256 signature of the request body. payload: $ref: '#/components/schemas/ProviderWebhookPayload' examples: - payload: action: resource.created resource_id: res_abc123 config: REDIS_URL: rediss://default:password@host:6379 ResourceUpdated: name: ResourceUpdated title: Extension Resource Updated summary: Notifies Fly.io that an extension resource has been updated description: >- Sent by an extension provider when a resource's configuration changes, such as after a plan upgrade or region change. The updated config object is applied to the user's Fly App environment variables. contentType: application/json headers: type: object properties: X-Fly-Signature: type: string description: HMAC-SHA256 signature of the request body. payload: $ref: '#/components/schemas/ProviderWebhookPayload' examples: - payload: action: resource.updated resource_id: res_abc123 config: REDIS_URL: rediss://default:newpassword@newhost:6379 ResourceDeleted: name: ResourceDeleted title: Extension Resource Deleted summary: Notifies Fly.io that an extension resource has been deleted description: >- Sent by an extension provider when a resource has been cleaned up and is no longer available. Fly.io removes the associated environment variables from the user's Fly App on receipt of this event. contentType: application/json headers: type: object properties: X-Fly-Signature: type: string description: HMAC-SHA256 signature of the request body. payload: type: object properties: action: type: string enum: [resource.deleted] description: The lifecycle action. resource_id: type: string description: The provider's ID of the deleted resource. examples: - payload: action: resource.deleted resource_id: res_abc123 MachineStarted: name: MachineStarted title: Fly Machine Started summary: Notifies the provider that a Fly Machine has started description: >- Fly.io sends this CloudEvent to the provider when a Fly Machine associated with an extension resource starts running. The provider can use this event to initialize connections or perform startup tasks. contentType: application/json headers: type: object properties: X-Fly-Signature: type: string description: HMAC-SHA256 signature of the request body. payload: $ref: '#/components/schemas/CloudEventPayload' examples: - payload: specversion: '1.0' type: io.fly.machine.started source: https://api.fly.io id: evt_01HXYZ time: '2026-03-21T00:00:00Z' datacontenttype: application/json data: machine_id: abc123def456 app_name: my-fly-app region: iad MachineStopped: name: MachineStopped title: Fly Machine Stopped summary: Notifies the provider that a Fly Machine has stopped description: >- Fly.io sends this CloudEvent to the provider when a Fly Machine associated with an extension resource stops. The provider can use this event to release resources or record usage. contentType: application/json headers: type: object properties: X-Fly-Signature: type: string description: HMAC-SHA256 signature of the request body. payload: $ref: '#/components/schemas/CloudEventPayload' examples: - payload: specversion: '1.0' type: io.fly.machine.stopped source: https://api.fly.io id: evt_01HABC time: '2026-03-21T01:00:00Z' datacontenttype: application/json data: machine_id: abc123def456 app_name: my-fly-app region: iad MachineDestroyed: name: MachineDestroyed title: Fly Machine Destroyed summary: Notifies the provider that a Fly Machine has been destroyed description: >- Fly.io sends this CloudEvent to the provider when a Fly Machine associated with an extension resource is permanently destroyed. Providers should clean up any resources or associations tied to this machine instance. contentType: application/json headers: type: object properties: X-Fly-Signature: type: string description: HMAC-SHA256 signature of the request body. payload: $ref: '#/components/schemas/CloudEventPayload' AccountChanged: name: AccountChanged title: Fly.io Account Changed summary: Notifies the provider that a Fly.io account has changed description: >- Fly.io sends this CloudEvent to the provider when an account or organization change occurs that may affect extension resources, such as a user being removed from an organization or a billing status change. contentType: application/json headers: type: object properties: X-Fly-Signature: type: string description: HMAC-SHA256 signature of the request body. payload: $ref: '#/components/schemas/CloudEventPayload' schemas: ProviderWebhookPayload: type: object description: >- Payload sent by an extension provider to Fly.io for resource lifecycle events. required: - action - resource_id properties: action: type: string description: The lifecycle action that occurred on the provider's resource. enum: [resource.created, resource.updated, resource.deleted] resource_id: type: string description: The provider's unique identifier for the affected resource. config: type: object description: >- Updated environment variable configuration for the resource. Required when action is resource.created or resource.updated. additionalProperties: type: string CloudEventPayload: type: object description: >- A CloudEvents 1.0 compliant payload sent by Fly.io to extension provider webhook endpoints for machine and account events. required: - specversion - type - source - id properties: specversion: type: string description: CloudEvents specification version. Always 1.0. enum: ['1.0'] type: type: string description: >- Event type identifier in reverse-DNS notation, such as io.fly.machine.started, io.fly.machine.stopped, or io.fly.account.changed. source: type: string description: URI of the Fly.io system that originated this event. example: https://api.fly.io id: type: string description: Unique identifier for this specific event instance. time: type: string format: date-time description: ISO 8601 timestamp of when the event occurred. datacontenttype: type: string description: MIME type of the event data payload. example: application/json data: type: object description: Event-specific data payload. additionalProperties: true