Fly.io Extensions Webhook Events

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