openapi: 3.1.0
info:
  title: Schoology Event Triggers (Webhooks) API
  description: |
    Schoology's documented webhook surface, called "Event Triggers". Schoology-defined
    actions ("triggers") fire against user-defined HTTP endpoints ("targets") that are
    linked via "subscriptions". Schoology POSTs event objects to the configured target
    URL and expects an HTTP 200 response. If a non-200 is received, the event is
    requeued and retried up to 5 times at 10 minute intervals, after which it is
    dropped.
    Source: https://developers.schoology.com/api-documentation/rest-api-triggers-v1/
    Event objects: https://developers.schoology.com/api-documentation/rest-api-triggers-v1/event_objects/
  version: "1.0"
servers:
  - url: https://api.schoology.com/v1
    description: Schoology REST API v1
security:
  - OAuth: []
paths:
  /triggers/targets:
    get:
      summary: List targets
      description: Lists target endpoints that Schoology can POST event objects to.
      operationId: listTriggerTargets
      tags: [Targets]
      responses:
        "200":
          description: A collection of trigger targets.
    post:
      summary: Create target
      description: Registers a new target endpoint to receive event POSTs from Schoology.
      operationId: createTriggerTarget
      tags: [Targets]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Target"
      responses:
        "201":
          description: Target created.
  /triggers/targets/{target_id}:
    put:
      summary: Edit target
      description: Updates an existing target endpoint.
      operationId: updateTriggerTarget
      tags: [Targets]
      parameters:
        - $ref: "#/components/parameters/TargetId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Target"
      responses:
        "200":
          description: Target updated.
    delete:
      summary: Delete target
      description: Removes a target endpoint.
      operationId: deleteTriggerTarget
      tags: [Targets]
      parameters:
        - $ref: "#/components/parameters/TargetId"
      responses:
        "204":
          description: Target deleted.
  /triggers/subscriptions:
    get:
      summary: List subscriptions
      description: Lists subscriptions linking targets to Schoology-defined triggers.
      operationId: listTriggerSubscriptions
      tags: [Subscriptions]
      responses:
        "200":
          description: A collection of subscriptions.
    put:
      summary: Create or modify subscriptions
      description: Creates or modifies subscriptions that link triggers to targets.
      operationId: upsertTriggerSubscriptions
      tags: [Subscriptions]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Subscription"
      responses:
        "200":
          description: Subscription created or modified.
webhooks:
  eventObject:
    post:
      summary: Receive event object
      description: |
        Schoology POSTs an event object to the configured target URL when a subscribed
        trigger fires. The target must respond with HTTP 200. Non-200 responses are
        retried up to 5 times at 10 minute intervals.
      operationId: receiveEventObject
      tags: [Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventObject"
      responses:
        "200":
          description: Acknowledgement. Anything other than 200 causes a retry.
components:
  securitySchemes:
    OAuth:
      type: oauth2
      description: OAuth 1.0a / 2.0 per Schoology Authentication docs.
      flows:
        authorizationCode:
          authorizationUrl: https://api.schoology.com/v1/oauth/authorize
          tokenUrl: https://api.schoology.com/v1/oauth/access_token
          scopes: {}
  parameters:
    TargetId:
      name: target_id
      in: path
      required: true
      schema: { type: string }
  schemas:
    Target:
      type: object
      description: A user-defined endpoint that Schoology POSTs event objects to.
      properties:
        id:
          type: integer
          description: Target identifier (assigned by Schoology).
        target:
          type: string
          description: The URL of the target resource. This is where data will be sent when a trigger action occurs.
        description:
          type: string
          description: Human-readable description of the target.
      required:
        - target
    Subscription:
      type: object
      description: Links a Schoology-defined trigger to a target.
      properties:
        target_id:
          type: integer
          description: Identifier of the target that should receive events for this trigger.
        trigger:
          type: string
          description: Name of the Schoology-defined trigger (for example grade_item, attendance, grades, section_completion, dropbox_submission).
        subscribed:
          type: integer
          enum: [0, 1]
          description: Whether the subscription is active (1) or inactive (0).
        include_object:
          type: integer
          enum: [0, 1]
          description: Whether to include the full object representation in the event payload.
        version:
          type: string
          description: API version of the subscription (for example "v1").
      required:
        - target_id
        - trigger
        - subscribed
        - version
    EventObject:
      type: object
      description: Payload Schoology POSTs to a target when a subscribed trigger fires.
      properties:
        uid:
          type: string
          description: Identifies who triggered the event.
        timestamp:
          type: string
          description: When the event occurred.
        type:
          type: string
          description: Trigger category and operation in the form "trigger_name.operation" (for example "grade_item.update", "grade_item.delete").
        data:
          type: object
          description: Contextual information about what happened or changed.
          properties:
            realm:
              type: string
              description: Realm context (course, group, section, school, district).
            realm_id:
              type: string
              description: Identifier within the realm.
            object:
              type: object
              description: Identical to the object returned from a GET list or single GET call for the resource (included when include_object is 1).
      required:
        - uid
        - timestamp
        - type