asyncapi: 3.0.0
info:
  title: Leap Webhook Events
  version: '1.1'
  description: |
    API Evangelist DERIVED AsyncAPI rendering of Leap's published webhook surface. Leap does not
    publish an AsyncAPI document; this document was derived from the public event catalog and the
    published example payloads at:

      * https://developer.leap.energy/reference/metercreated  (event index)
      * https://developer.leap.energy/reference/connect-events
      * https://developer.leap.energy/reference/meter-events
      * https://developer.leap.energy/docs/webhook-setup
      * https://developer.leap.energy/docs/retry-mechanism
      * https://developer.leap.energy/docs/webhook-push-notifications-v2

    Leap operates TWO independent event surfaces:

      1. The general webhook platform (out of beta since November 2025, managed under /v1.1/webhooks)
         which delivers connect-session and meter/enrollment events using a common
         {webhook_event_id, payload{webhook_event_type, ...}} envelope.
      2. The older dispatch notification surface, configured separately per meter or market group
         through the Dispatch API V2 webhook endpoints, which posts dispatch timeslots with no
         webhook_event_type discriminator.

    Field names, enumerations and example values below are taken verbatim from Leap's published
    example payloads. No fields have been invented; where Leap does not document a type it is
    left loose.
  contact:
    name: Leap API team
    url: https://developer.leap.energy/
    email: apiteam@leap.energy
  externalDocs:
    url: https://developer.leap.energy/docs/webhook-setup
defaultContentType: application/json
servers:
  partner-receiver:
    host: partner-supplied-receiver.example.com
    protocol: https
    description: |
      The partner's own HTTPS receiver. Leap requires TCP port 443, 8443 or 8843 with TLS 1.2 or
      1.3, a JSON body, and any 2xx response within 10 seconds. General-platform webhook URLs are
      registered through POST /v1.1/webhooks (or the Partner Portal); dispatch webhook URLs are
      registered through PUT /v2/dispatch/meter/webhook and PUT /v2/dispatch/group/webhook.
channels:
  platformEvents:
    address: /
    title: Leap webhook platform events
    description: >-
      Partner receiver URL registered through the general webhook platform. The event types the
      receiver gets are selected at subscription time.
    messages:
      connectSessionUpdated:
        $ref: '#/components/messages/connectSessionUpdated'
      connectSessionAuthorizationUpdated:
        $ref: '#/components/messages/connectSessionAuthorizationUpdated'
      meterCreated:
        $ref: '#/components/messages/meterCreated'
      meterEnrollmentGlobalStatusUpdated:
        $ref: '#/components/messages/meterEnrollmentGlobalStatusUpdated'
      meterEnrollmentRequiredActionsUpdated:
        $ref: '#/components/messages/meterEnrollmentRequiredActionsUpdated'
      meterEnrollmentParticipationStatusUpdated:
        $ref: '#/components/messages/meterEnrollmentParticipationStatusUpdated'
      meterEnrollmentGroupUpdated:
        $ref: '#/components/messages/meterEnrollmentGroupUpdated'
  meterDispatchNotifications:
    address: /
    title: Meter-level dispatch notifications
    description: >-
      Receiver URL registered with PUT /v2/dispatch/meter/webhook. Delivered as grid dispatch
      instructions become available; retried every minute for up to 50 attempts.
    messages:
      meterDispatchNotification:
        $ref: '#/components/messages/meterDispatchNotification'
  groupDispatchNotifications:
    address: /
    title: Market-group dispatch notifications
    description: >-
      Receiver URL registered with PUT /v2/dispatch/group/webhook, for partners that dispatch
      pre-configured VPP market groups rather than individual meters.
    messages:
      groupDispatchNotification:
        $ref: '#/components/messages/groupDispatchNotification'
operations:
  receivePlatformEvent:
    action: receive
    channel:
      $ref: '#/channels/platformEvents'
    summary: Receive a Leap webhook platform event
    description: >-
      Return any 2xx within 10 seconds. Leap retries up to 10 times over 8 hours at increasing
      intervals (immediate, 1m, 2m, 4m, 8m, 16m, 29m, 1h, 2h, 4h).
  receiveMeterDispatch:
    action: receive
    channel:
      $ref: '#/channels/meterDispatchNotifications'
    summary: Receive a meter-level dispatch notification
    description: >-
      Acknowledge with 2xx before scheduling the events downstream. Retries occur every minute for
      up to 50 minutes; a dropped acknowledgement can produce a duplicate notification, so the
      receiver must be able to de-duplicate on meter_event_id.
  receiveGroupDispatch:
    action: receive
    channel:
      $ref: '#/channels/groupDispatchNotifications'
    summary: Receive a market-group dispatch notification
    description: >-
      Same delivery and retry semantics as meter-level dispatch, keyed on market_group_event_id.
components:
  messages:
    connectSessionUpdated:
      name: connect_session.updated
      title: Leap Connect session updated
      summary: A customer Leap Connect session was created, advanced, closed or completed.
      payload:
        $ref: '#/components/schemas/ConnectSessionUpdated'
      examples:
      - name: created
        payload:
          webhook_event_id: cca07005-1406-4539-8b84-1a5f24cd1575
          payload:
            webhook_event_type: connect_session.updated
            partner_reference: customer-site-123
            status: CREATED
    connectSessionAuthorizationUpdated:
      name: connect_session.authorization_updated
      title: Utility authorization updated
      summary: A utility data-sharing authorization (Leap Connect redirect or CAISO direct-to-utility) changed state.
      payload:
        $ref: '#/components/schemas/ConnectSessionAuthorizationUpdated'
      examples:
      - name: initiated
        payload:
          webhook_event_id: 3b41a28a-46b3-4082-b13c-a2f812f1bda5
          payload:
            webhook_event_type: connect_session.authorization_updated
            partner_reference: customer-site-123
            utility_name: PGE
            status: INITIATED
    meterCreated:
      name: meter.created
      title: Meter created
      summary: A new meter was created in the partner account, partner-created or customer-authorized.
      payload:
        $ref: '#/components/schemas/MeterCreated'
      examples:
      - name: created
        payload:
          webhook_event_id: 26c8b7c6-3d3c-4d84-9ce9-734930c897d4
          payload:
            webhook_event_type: meter.created
            meter_id: 11111111-1111-1111-1111-111111111111
            partner_reference: customer-site-123
            transmission_region: CAISO
            meter_type: UTILITY_METER
    meterEnrollmentGlobalStatusUpdated:
      name: meter.enrollment.global-status.updated
      title: Global enrollment status updated
      payload:
        $ref: '#/components/schemas/MeterEnrollmentGlobalStatusUpdated'
    meterEnrollmentRequiredActionsUpdated:
      name: meter.enrollment.required-actions.updated
      title: Required partner actions updated
      summary: >-
        New, updated or resolved partner actions on a meter. When every action is resolved a final
        event carries an empty required_actions object.
      payload:
        $ref: '#/components/schemas/MeterEnrollmentRequiredActionsUpdated'
    meterEnrollmentParticipationStatusUpdated:
      name: meter.enrollment.participation-status.updated
      title: Participation preference updated
      payload:
        $ref: '#/components/schemas/MeterEnrollmentParticipationStatusUpdated'
    meterEnrollmentGroupUpdated:
      name: meter.enrollment.group.updated
      title: VPP market group updated
      summary: The start date, end date or meter membership of a VPP market group changed.
      payload:
        $ref: '#/components/schemas/MeterEnrollmentGroupUpdated'
    meterDispatchNotification:
      name: meter_dispatch_notification
      title: Meter dispatch notification
      payload:
        $ref: '#/components/schemas/MeterDispatchNotification'
    groupDispatchNotification:
      name: group_dispatch_notification
      title: Market group dispatch notification
      payload:
        $ref: '#/components/schemas/GroupDispatchNotification'
  schemas:
    WebhookEnvelope:
      type: object
      description: Common envelope for every general-platform webhook event.
      properties:
        webhook_event_id:
          type: string
          format: uuid
        payload:
          type: object
    ConnectSessionUpdated:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          payload:
            type: object
            properties:
              webhook_event_type:
                type: string
                const: connect_session.updated
              partner_reference:
                type: string
              status:
                type: string
                enum: [CREATED, UPDATED, CLOSED, COMPLETED]
                description: >-
                  CREATED - user reaches the initial screen; UPDATED - user moves to the next step;
                  CLOSED - user exits prematurely; COMPLETED - user completes the final step. A new
                  session starts on a new Connect tab or after a 24-hour idle expiry.
    ConnectSessionAuthorizationUpdated:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          payload:
            type: object
            properties:
              webhook_event_type:
                type: string
                const: connect_session.authorization_updated
              partner_reference:
                type: string
              utility_name:
                type: string
                examples: [PGE]
              status:
                type: string
                enum: [INITIATED, COMPLETED, FAILED]
                description: >-
                  INITIATED - user reaches the utility login screen; COMPLETED - authorization
                  succeeded; FAILED - invalid credentials, MFA error, utility error or cancellation.
    MeterCreated:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          payload:
            type: object
            properties:
              webhook_event_type:
                type: string
                const: meter.created
              meter_id:
                type: string
                format: uuid
              partner_reference:
                type: string
              transmission_region:
                type: string
                examples: [CAISO]
              meter_type:
                type: string
                examples: [UTILITY_METER, DEVICE]
    MeterEnrollmentGlobalStatusUpdated:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          payload:
            type: object
            properties:
              webhook_event_type:
                type: string
                const: meter.enrollment.global-status.updated
              global_enrollment_status:
                type: string
                examples: [ELIGIBLE, INELIGIBLE]
              meter_id:
                type: string
                format: uuid
              partner_reference:
                type: string
              transmission_region:
                type: string
              meter_type:
                type: string
    MeterEnrollmentRequiredActionsUpdated:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          payload:
            type: object
            properties:
              webhook_event_type:
                type: string
                const: meter.enrollment.required-actions.updated
              meter_id:
                type: string
                format: uuid
              transmission_region:
                type: string
              global_enrollment_status:
                type: string
              partner_reference:
                type: string
              meter_type:
                type: string
              required_actions:
                type: object
                description: Empty object once every action is resolved.
                properties:
                  partner:
                    type: array
                    items:
                      type: object
                      properties:
                        enrollment_deadline_date_time:
                          type: string
                          format: date-time
                        action_type:
                          type: string
                          examples: [NO_MISSING_FIELDS]
                        action_description:
                          type: string
                        action_code:
                          type: string
                          examples: [SERV_0005]
                        program_identifier:
                          type: string
                          examples: [CEC-DSGS]
                        delivery_period:
                          type: string
                          examples: [CEC-DSGS_2026_MAY_OCT]
    MeterEnrollmentParticipationStatusUpdated:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          payload:
            type: object
            properties:
              webhook_event_type:
                type: string
                const: meter.enrollment.participation-status.updated
              participation_preference:
                type: string
                enum: [PARTICIPATE, IDLE, DISENROLL]
              start_time:
                type: string
                format: date-time
              meter_id:
                type: string
                format: uuid
              partner_reference:
                type: string
              transmission_region:
                type: string
              meter_type:
                type: string
    MeterEnrollmentGroupUpdated:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelope'
      - type: object
        properties:
          payload:
            type: object
            properties:
              webhook_event_type:
                type: string
                const: meter.enrollment.group.updated
              market_group_id:
                type: string
                format: uuid
              market_group_name:
                type: string
              start_date_time:
                type: string
                format: date-time
              end_date_time:
                type: string
                format: date-time
              meter_ids:
                type: array
                items:
                  type: string
                  format: uuid
    DispatchTimeslot:
      type: object
      properties:
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        cancelled:
          type: boolean
        performance_compensation_cap:
          type: string
          examples: [up-to-site-load, grid-exports-allowed]
        priority:
          type: integer
        is_voluntary:
          type: boolean
        dispatch_event_types:
          type: array
          items:
            type: string
            examples: [day-ahead, hour-ahead, standard, capacity-test]
        programs:
          type: array
          items:
            type: string
            examples: [CCA, ELRP]
        energy_kw:
          type: [number, 'null']
          description: >-
            Awarded kW for the dispatch — the expected power to be curtailed or exported for the
            duration of the event. When null, dispatch the maximum you can manage.
        nomination_kw:
          type: [number, 'null']
          description: The nomination in kW — the commitment made to the market for this asset.
    MeterDispatchNotification:
      type: object
      properties:
        integration_test_notification:
          type: boolean
          description: true when triggered by triggerTestMeterDispatchNotification, false for real events.
        communication_test:
          type: boolean
        meter_dispatches:
          type: array
          items:
            type: object
            properties:
              meter_id:
                type: string
                format: uuid
              partner_reference:
                type: string
                description: Added to all dispatch notifications in December 2025.
              timeslots:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/DispatchTimeslot'
                  - type: object
                    properties:
                      meter_event_id:
                        type: string
                        format: uuid
    GroupDispatchNotification:
      type: object
      properties:
        integration_test_notification:
          type: boolean
        communication_test:
          type: boolean
        group_dispatches:
          type: array
          items:
            type: object
            properties:
              market_group_id:
                type: string
                format: uuid
              meter_ids:
                type: array
                items:
                  type: string
                  format: uuid
              timeslots:
                type: array
                items:
                  allOf:
                  - $ref: '#/components/schemas/DispatchTimeslot'
                  - type: object
                    properties:
                      market_group_event_id:
                        type: string
                        format: uuid