openapi: 3.0.2
info:
  title: Zeplin Authorization Webhooks API
  description: Access your resources in Zeplin
  version: 1.38.0
  contact:
    name: Zeplin
    url: https://zeplin.io
    email: support@zeplin.io
servers:
- url: https://api.zeplin.dev
security:
- PersonalAccessToken: []
- OAuth2: []
tags:
- name: Webhooks
paths:
  /v1/organizations/{organization_id}/webhooks:
    get:
      tags:
      - Webhooks
      summary: Get organization webhooks
      description: 'List all webhooks of organization


        Note: Zeplin apps can only list the webhook that are created by them.

        To list all webhooks created by any app or without app, personal access token is needed.

        '
      operationId: GetOrganizationWebhooks
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/webhook_status'
      - $ref: '#/components/parameters/url_health'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationWebhook'
              examples:
                Organization Webhooks:
                  value:
                  - $ref: '#/components/examples/webhook/value'
        '403':
          $ref: '#/components/responses/cannotGetWebhook'
        '404':
          $ref: '#/components/responses/organizationNotFound'
    post:
      tags:
      - Webhooks
      summary: Create organization webhooks
      description: 'Create a webhook for the organization


        Wildcard `"*"` can be used for `project_ids` and `styleguide_ids` to receive events for all projects and styleguides that you own. You''ll also automatically subscribe to the new ones you create in the future.


        Note: Users that have authorized the app before webhooks release must re-authorize the app to create webhooks.

        '
      operationId: CreateOrganizationWebhooks
      parameters:
      - $ref: '#/components/parameters/organization_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationWebhookCreateBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityReference'
              examples:
                response:
                  $ref: '#/components/examples/entityReference'
        '403':
          $ref: '#/components/responses/cannotCreateOrganizationWebhook'
        '422':
          $ref: '#/components/responses/unprocessableEntityCreateWebhook'
  /v1/organizations/{organization_id}/webhooks/{webhook_id}:
    get:
      tags:
      - Webhooks
      summary: Get a webhook of organization
      description: Get a webhook by id
      operationId: GetOrganizationWebhook
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationWebhook'
              examples:
                response:
                  $ref: '#/components/examples/webhook'
        '403':
          $ref: '#/components/responses/cannotGetWebhook'
        '404':
          $ref: '#/components/responses/organizationWebhookNotFound'
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook of an organization
      description: Delete a webhook by id
      operationId: DeleteOrganizationWebhook
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotDeleteOrganizationWebhook'
        '404':
          $ref: '#/components/responses/organizationWebhookNotFound'
    patch:
      tags:
      - Webhooks
      summary: Update organization webhooks
      description: Update a webhook for the organization
      operationId: UpdateOrganizationWebhooks
      parameters:
      - $ref: '#/components/parameters/organization_id'
      - $ref: '#/components/parameters/webhook_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationWebhookUpdateBody'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotUpdateOrganizationWebhook'
        '404':
          $ref: '#/components/responses/organizationWebhookNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityUpdateWebhook'
  /v1/projects/{project_id}/webhooks:
    get:
      tags:
      - Webhooks
      summary: Get project webhooks
      description: 'List all webhooks of the project


        Note: Zeplin apps can only list the webhook that are created by them.

        To list all webhooks created by any app or without app, personal access token is needed.

        '
      operationId: GetProjectWebhooks
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/webhook_status'
      - $ref: '#/components/parameters/url_health'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectWebhook'
              examples:
                Project Webhooks:
                  value:
                  - $ref: '#/components/examples/projectWebhook/value'
        '403':
          $ref: '#/components/responses/cannotAccessProjectWebhook'
        '404':
          $ref: '#/components/responses/projectNotFound'
        '422':
          $ref: '#/components/responses/notAProjectMemberOrArchived'
    post:
      tags:
      - Webhooks
      summary: Create project webhooks
      description: 'Create a webhook for the project


        Note: Users that have authorized the app before webhooks release must re-authorize the app to create webhooks.

        '
      operationId: CreateProjectWebhooks
      parameters:
      - $ref: '#/components/parameters/project_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectWebhookCreateBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityReference'
              examples:
                response:
                  $ref: '#/components/examples/entityReference'
        '403':
          $ref: '#/components/responses/forbiddenCreateProjectWebhook'
        '404':
          $ref: '#/components/responses/projectNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityCreateProjectWebhook'
  /v1/projects/{project_id}/webhooks/{webhook_id}:
    get:
      tags:
      - Webhooks
      summary: Get a webhook of project
      description: Get a webhook by id
      operationId: GetProjectWebhook
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectWebhook'
              examples:
                response:
                  $ref: '#/components/examples/projectWebhook'
        '403':
          $ref: '#/components/responses/cannotAccessProjectWebhook'
        '404':
          $ref: '#/components/responses/projectWebhookNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityProjectWebhook'
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook of a project
      description: Delete a webhook by id
      operationId: DeleteProjectWebhook
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotDeleteProjectWebhook'
        '404':
          $ref: '#/components/responses/projectWebhookNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityProjectWebhook'
    patch:
      tags:
      - Webhooks
      summary: Update project webhooks
      description: Update a webhook for the project
      operationId: UpdateProjectWebhooks
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/webhook_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectWebhookUpdateBody'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotUpdateProjectWebhook'
        '404':
          $ref: '#/components/responses/projectWebhookNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityUpdateProjectWebhook'
  /v1/styleguides/{styleguide_id}/webhooks:
    get:
      tags:
      - Webhooks
      summary: Get styleguide webhooks
      description: 'List all webhooks of the styleguide


        Note: Zeplin apps can only list the webhook that are created by them.

        To list all webhooks created by any app or without app, personal access token is needed.

        '
      operationId: GetStyleguideWebhooks
      parameters:
      - $ref: '#/components/parameters/styleguide_id'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/webhook_status'
      - $ref: '#/components/parameters/url_health'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/StyleguideWebhook'
              examples:
                Styleguide Webhooks:
                  value:
                  - $ref: '#/components/examples/styleguideWebhook/value'
        '403':
          $ref: '#/components/responses/cannotAccessStyleguideWebhook'
        '404':
          $ref: '#/components/responses/styleguideNotFound'
        '422':
          $ref: '#/components/responses/notAStyleguideMemberOrArchived'
    post:
      tags:
      - Webhooks
      summary: Create styleguide webhooks
      description: 'Create a webhook for the styleguide


        Note: Users that have authorized the app before webhooks release must re-authorize the app to create webhooks.

        '
      operationId: CreateStyleguideWebhooks
      parameters:
      - $ref: '#/components/parameters/styleguide_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StyleguideWebhookCreateBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityReference'
              examples:
                response:
                  $ref: '#/components/examples/entityReference'
        '403':
          $ref: '#/components/responses/forbiddenCreateStyleguideWebhook'
        '404':
          $ref: '#/components/responses/styleguideNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityCreateStyleguideWebhook'
  /v1/styleguides/{styleguide_id}/webhooks/{webhook_id}:
    get:
      tags:
      - Webhooks
      summary: Get a webhook of styleguide
      description: Get a webhook by id
      operationId: GetStyleguideWebhook
      parameters:
      - $ref: '#/components/parameters/styleguide_id'
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StyleguideWebhook'
              examples:
                response:
                  $ref: '#/components/examples/styleguideWebhook'
        '403':
          $ref: '#/components/responses/cannotAccessStyleguideWebhook'
        '404':
          $ref: '#/components/responses/styleguideWebhookNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityStyleguideWebhook'
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook of a styleguide
      description: Delete a webhook by id
      operationId: DeleteStyleguideWebhook
      parameters:
      - $ref: '#/components/parameters/styleguide_id'
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotDeleteStyleguideWebhook'
        '404':
          $ref: '#/components/responses/styleguideWebhookNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityStyleguideWebhook'
    patch:
      tags:
      - Webhooks
      summary: Update styleguide webhooks
      description: Update a webhook for the styleguide
      operationId: UpdateStyleguideWebhooks
      parameters:
      - $ref: '#/components/parameters/styleguide_id'
      - $ref: '#/components/parameters/webhook_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StyleguideWebhookUpdateBody'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotUpdateStyleguideWebhook'
        '404':
          $ref: '#/components/responses/styleguideWebhookNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityUpdateStyleguideWebhook'
  /v1/users/me/webhooks:
    get:
      tags:
      - Webhooks
      summary: Get user webhooks
      description: 'List all webhooks of the user


        Note: Zeplin apps can only list the webhook that are created by them.

        To list all webhooks created by any app or without app, personal access token is needed.

        '
      operationId: GetUserWebhooks
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/webhook_status'
      - $ref: '#/components/parameters/url_health'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserWebhook'
              examples:
                User Webhooks:
                  value:
                  - $ref: '#/components/examples/webhook/value'
    post:
      tags:
      - Webhooks
      summary: Create user webhooks
      description: 'Create a webhook for the user


        Wildcard `"*"` can be used for `project_ids` and `styleguide_ids` to receive events for all projects and styleguides that you own. You''ll also automatically subscribe to the new ones you create in the future.


        Note: Users that have authorized the app before webhooks release must re-authorize the app to create webhooks.

        '
      operationId: CreateUserWebhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserWebhookCreateBody'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityReference'
              examples:
                response:
                  $ref: '#/components/examples/entityReference'
        '403':
          $ref: '#/components/responses/cannotCreateUserWebhook'
        '422':
          $ref: '#/components/responses/unprocessableEntityCreateWebhook'
  /v1/users/me/webhooks/{webhook_id}:
    get:
      tags:
      - Webhooks
      summary: Get a webhook of user
      description: Get a webhook by id
      operationId: GetUserWebhook
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserWebhook'
              examples:
                response:
                  $ref: '#/components/examples/webhook'
        '404':
          $ref: '#/components/responses/userWebhookNotFound'
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook of a user
      description: Delete a webhook by id
      operationId: DeleteUserWebhook
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotDeleteUserWebhook'
        '404':
          $ref: '#/components/responses/userWebhookNotFound'
    patch:
      tags:
      - Webhooks
      summary: Update user webhooks
      description: Update a webhook for the user
      operationId: UpdateUserWebhooks
      parameters:
      - $ref: '#/components/parameters/webhook_id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserWebhookUpdateBody'
      responses:
        '204':
          $ref: '#/components/responses/noContent'
        '403':
          $ref: '#/components/responses/cannotUpdateUserWebhook'
        '404':
          $ref: '#/components/responses/userWebhookNotFound'
        '422':
          $ref: '#/components/responses/unprocessableEntityUpdateWebhook'
components:
  schemas:
    ProjectWebhook:
      title: Project Webhook
      type: object
      required:
      - id
      - url
      - status
      - url_health
      - created
      - updated
      - created_by
      - updated_by
      - events
      properties:
        id:
          type: string
          description: The unique id of the webhook
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        status:
          $ref: '#/components/schemas/WebhookStatusEnum'
        url_health:
          $ref: '#/components/schemas/WebhookHealthEnum'
        created:
          type: number
          description: The unix timestamp when the webhook was created
        updated:
          type: number
          description: The unix timestamp when the webhook was updated
        created_by:
          allOf:
          - $ref: '#/components/schemas/User'
          - description: The user that creates the webhook
        updated_by:
          allOf:
          - $ref: '#/components/schemas/User'
          - description: The user that updates the webhook recently
        zeplin_app:
          allOf:
          - $ref: '#/components/schemas/ZeplinApplication'
          - description: The app that uses and manages the webhook
        events:
          type: array
          items:
            $ref: '#/components/schemas/ProjectWebhookEventEnum'
          minItems: 1
          uniqueItems: true
          description: The events of the webhook
      example:
        $ref: '#/components/examples/projectWebhook'
    OrganizationWebhookUpdateBody:
      title: Organization Webhook Update Body
      type: object
      properties:
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        secret:
          type: string
          description: The secret to be used to generate signatures for webhook requests
        status:
          title: status
          $ref: '#/components/schemas/WebhookStatusEnum'
        project_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: The project ids of the webhook
        styleguide_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: The styleguide ids of the webhook
        events:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/OrganizationWebhookEventEnum'
          minItems: 1
          description: The events of the webhook
    ProjectWebhookCreateBody:
      title: Project Webhook Create Body
      type: object
      properties:
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        secret:
          type: string
          description: The secret to be used to generate signatures for webhook requests
        status:
          title: status
          allOf:
          - $ref: '#/components/schemas/WebhookStatusEnum'
          - default: active
        events:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ProjectWebhookEventEnum'
          minItems: 1
          description: The events of the webhook
      required:
      - events
      - url
      - secret
    OrganizationWebhookCreateBody:
      title: Organization Webhook Create Body
      type: object
      properties:
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        secret:
          type: string
          description: The secret to be used to generate signatures for webhook requests
        status:
          title: status
          allOf:
          - $ref: '#/components/schemas/WebhookStatusEnum'
          - default: active
        project_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: The project ids of the webhook
        styleguide_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: The styleguide ids of the webhook
        events:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/OrganizationWebhookEventEnum'
          minItems: 1
          description: The events of the webhook
      required:
      - events
      - project_ids
      - styleguide_ids
      - url
      - secret
    WebhookStatusEnum:
      title: Webhook Status
      type: string
      enum:
      - active
      - inactive
      description: The status of the webhook
    OrganizationWebhookEventEnum:
      title: Organization Webhook Event Type
      type: string
      enum:
      - '*'
      - project.*
      - project.color
      - project.component
      - project.member
      - project.note
      - project.note.comment
      - project.note.comment.reaction
      - project.screen
      - project.screen.version
      - project.spacing_token
      - project.text_style
      - styleguide.*
      - styleguide.color
      - styleguide.component
      - styleguide.member
      - styleguide.spacing_token
      - styleguide.text_style
      - workspace.*
      - workspace.project
      - workspace.styleguide
      - workspace.organization
      - workspace.organization.member
    ErrorResponse:
      title: Error Response
      type: object
      required:
      - message
      properties:
        message:
          type: string
          description: A user readable descriptive message for the error
        detail:
          type: string
          description: A detailed message describing the error
        code:
          type: string
          description: The unique code for the error
      example:
        $ref: '#/components/examples/error'
    EntityReference:
      title: Object Reference
      type: object
      required:
      - id
      properties:
        id:
          type: string
          description: Id of the entity
      example:
        $ref: '#/components/examples/entityReference'
    UserWebhookEventEnum:
      title: User Webhook Event Type
      type: string
      enum:
      - '*'
      - project.*
      - project.color
      - project.component
      - project.member
      - project.note
      - project.note.comment
      - project.note.comment.reaction
      - project.screen
      - project.screen.version
      - project.spacing_token
      - project.text_style
      - styleguide.*
      - styleguide.color
      - styleguide.component
      - styleguide.member
      - styleguide.spacing_token
      - styleguide.text_style
      - workspace.*
      - workspace.notification
      - workspace.project
      - workspace.styleguide
    ZeplinApplication:
      title: Zeplin Application
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: The unique id of the app
        name:
          type: string
          description: The name of the app
        description:
          type: string
          description: The description of the app
        website:
          type: string
          description: The website of the app
        logo:
          type: string
          description: The logo of the app
      example:
        $ref: '#/components/examples/zeplinApplication'
    User:
      title: User
      description: 'Basic info about Zeplin users.


        Zeplin API does not expose any personal information to third-party clients. For this reason, the `email` field is a Zeplin-only alias by default.


        You can get the original email addresses of members of your workspace by using a personal access token created with admin rights. Third-party (OAuth) applications are not allowed to access this information.


        ☝️*Only organization admins (or higher) can retrieve the original email addresses using an admin token.*

        '
      type: object
      required:
      - id
      - email
      - username
      properties:
        id:
          type: string
          description: User's unique id
        email:
          type: string
          description: Zeplin-only alias for the user's email (original)
        username:
          type: string
          description: Username of the user
        emotar:
          type: string
          format: emoji
          description: Emotar of the user
        avatar:
          type: string
          description: Avatar of the user
        last_seen:
          type: number
          description: The unix timestamp when the user was last seen
      example:
        $ref: '#/components/examples/user'
      x-examples:
        User:
          $ref: '#/components/examples/user'
        My User:
          $ref: '#/components/examples/me'
    ProjectWebhookUpdateBody:
      title: Project Webhook Update Body
      type: object
      properties:
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        secret:
          type: string
          description: The secret to be used to generate signatures for webhook requests
        status:
          title: status
          $ref: '#/components/schemas/WebhookStatusEnum'
        events:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/ProjectWebhookEventEnum'
          minItems: 1
          description: The events of the webhook
    WebhookHealthEnum:
      title: Webhook Health
      type: string
      enum:
      - healthy
      - unhealthy
      description: The health of a webhook URL
    UserWebhookUpdateBody:
      title: User Webhook Update Body
      type: object
      properties:
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        secret:
          type: string
          description: The secret to be used to generate signatures for webhook requests
        status:
          title: status
          $ref: '#/components/schemas/WebhookStatusEnum'
        project_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: The project ids of the webhook
        styleguide_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: The styleguide ids of the webhook
        events:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/UserWebhookEventEnum'
          minItems: 1
          description: The events of the webhook
    UserWebhookCreateBody:
      title: User Webhook Create Body
      type: object
      properties:
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        secret:
          type: string
          description: The secret to be used to generate signatures for webhook requests
        status:
          title: status
          allOf:
          - $ref: '#/components/schemas/WebhookStatusEnum'
          - default: active
        project_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: The project ids of the webhook
        styleguide_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: The styleguide ids of the webhook
        events:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/UserWebhookEventEnum'
          minItems: 1
          description: The events of the webhook
      required:
      - events
      - project_ids
      - styleguide_ids
      - url
      - secret
    StyleguideWebhookEventEnum:
      title: Styleguide Webhook Event Type
      type: string
      enum:
      - styleguide.*
      - styleguide.color
      - styleguide.component
      - styleguide.member
      - styleguide.spacing_token
      - styleguide.text_style
    OrganizationWebhook:
      title: Organization Webhook
      type: object
      required:
      - id
      - url
      - status
      - url_health
      - created
      - updated
      - created_by
      - updated_by
      - events
      - project_ids
      - styleguide_ids
      properties:
        id:
          type: string
          description: The unique id of the webhook
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        status:
          $ref: '#/components/schemas/WebhookStatusEnum'
        url_health:
          $ref: '#/components/schemas/WebhookHealthEnum'
        created:
          type: number
          description: The unix timestamp when the webhook was created
        updated:
          type: number
          description: The unix timestamp when the webhook was updated
        created_by:
          allOf:
          - $ref: '#/components/schemas/User'
          - description: The user that creates the webhook
        updated_by:
          allOf:
          - $ref: '#/components/schemas/User'
          - description: The user that updates the webhook recently
        zeplin_app:
          allOf:
          - $ref: '#/components/schemas/ZeplinApplication'
          - description: The app that uses and manages the webhook
        events:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationWebhookEventEnum'
          minItems: 1
          uniqueItems: true
          description: The events of the webhook
        project_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: 'The project ids of the webhooks. Note: `*` wildcard denotes all project_ids'
        styleguide_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: 'The styleguide ids of the webhooks. Note: `*` wildcard denotes all styleguide_ids'
      example:
        $ref: '#/components/examples/webhook'
    ProjectWebhookEventEnum:
      title: Project Webhook Event Type
      type: string
      enum:
      - project.*
      - project.color
      - project.component
      - project.member
      - project.note
      - project.note.comment
      - project.note.comment.reaction
      - project.screen
      - project.screen.version
      - project.spacing_token
      - project.text_style
      - project.flow_board
    UserWebhook:
      title: User Webhook
      type: object
      required:
      - id
      - url
      - status
      - url_health
      - created
      - updated
      - created_by
      - updated_by
      - events
      - project_ids
      - styleguide_ids
      properties:
        id:
          type: string
          description: The unique id of the webhook
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        status:
          $ref: '#/components/schemas/WebhookStatusEnum'
        url_health:
          $ref: '#/components/schemas/WebhookHealthEnum'
        created:
          type: number
          description: The unix timestamp when the webhook was created
        updated:
          type: number
          description: The unix timestamp when the webhook was updated
        created_by:
          allOf:
          - $ref: '#/components/schemas/User'
          - description: The user that creates the webhook
        updated_by:
          allOf:
          - $ref: '#/components/schemas/User'
          - description: The user that updates the webhook recently
        zeplin_app:
          allOf:
          - $ref: '#/components/schemas/ZeplinApplication'
          - description: The app that uses and manages the webhook
        events:
          type: array
          items:
            $ref: '#/components/schemas/UserWebhookEventEnum'
          minItems: 1
          uniqueItems: true
          description: The events of the webhook
        project_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: 'The project ids of the webhooks. Note: `*` wildcard denotes all project_ids'
        styleguide_ids:
          type: array
          items:
            type: string
          uniqueItems: true
          description: 'The styleguide ids of the webhooks. Note: `*` wildcard denotes all styleguide_ids'
      example:
        $ref: '#/components/examples/webhook'
    StyleguideWebhookUpdateBody:
      title: Styleguide Webhook Update Body
      type: object
      properties:
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        secret:
          type: string
          description: The secret to be used to generate signatures for webhook requests
        status:
          title: status
          $ref: '#/components/schemas/WebhookStatusEnum'
        events:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/StyleguideWebhookEventEnum'
          minItems: 1
          description: The events of the webhook
    StyleguideWebhookCreateBody:
      title: Styleguide Webhook Create Body
      type: object
      properties:
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        secret:
          type: string
          description: The secret to be used to generate signatures for webhook requests
        status:
          title: status
          allOf:
          - $ref: '#/components/schemas/WebhookStatusEnum'
          - default: active
        events:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/StyleguideWebhookEventEnum'
          minItems: 1
          description: The events of the webhook
      required:
      - events
      - url
      - secret
    StyleguideWebhook:
      title: Styleguide Webhook
      type: object
      required:
      - id
      - url
      - status
      - url_health
      - created
      - updated
      - created_by
      - updated_by
      - events
      properties:
        id:
          type: string
          description: The unique id of the webhook
        url:
          type: string
          description: The URL of the webhook
        name:
          type: string
          description: The name of the webhook
        status:
          $ref: '#/components/schemas/WebhookStatusEnum'
        url_health:
          $ref: '#/components/schemas/WebhookHealthEnum'
        created:
          type: number
          description: The unix timestamp when the webhook was created
        updated:
          type: number
          description: The unix timestamp when the webhook was updated
        created_by:
          allOf:
          - $ref: '#/components/schemas/User'
          - description: The user that creates the webhook
        updated_by:
          allOf:
          - $ref: '#/components/schemas/User'
          - description: The user that updates the webhook recently
        zeplin_app:
          allOf:
          - $ref: '#/components/schemas/ZeplinApplication'
          - description: The app that uses and manages the webhook
        events:
          type: array
          items:
            $ref: '#/components/schemas/StyleguideWebhookEventEnum'
          minItems: 1
          uniqueItems: true
          description: The events of the webhook
      example:
        $ref: '#/components/examples/styleguideWebhook'
  responses:
    cannotDeleteStyleguideWebhook:
      description: User cannot delete styleguide webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Organization styleguide webhook:
              value:
                message: Only organization editor (or higher) can access styleguide webhooks
            Personal styleguide webhook:
              value:
                message: Only owner of the styleguide can access webhooks
            Cannot delete app webhook:
              value:
                message: User cannot delete webhooks created by Zeplin apps
    cannotAccessStyleguideWebhook:
      description: User cannot access styleguide webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Organization styleguide webhook:
              value:
                message: Only organization editor (or higher) can access styleguide webhooks
            Personal styleguide webhook:
              value:
                message: Only owner of the styleguide can access webhooks
    unprocessableEntityProjectWebhook:
      description: Not a project member or project archived
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Not a member:
              value:
                message: User is not a member of the project
            Project is archived:
              value:
                message: Project is archived
    unprocessableEntityStyleguideWebhook:
      description: Not a styleguide member or styleguide archived
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Not a member:
              value:
                message: User is not a member of the styleguide
            Styleguide is archived:
              value:
                message: Styleguide is archived
    unprocessableEntityCreateStyleguideWebhook:
      description: Cannot create a styleguide webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            URL unhealthy with status active:
              value:
                message: Cannot create a webhook with active status because provided URL is unhealthy
            Styleguide is archived:
              value:
                message: Styleguide is archived
            Not a member:
              value:
                message: User is not a member of the styleguide
    cannotDeleteOrganizationWebhook:
      description: User cannot delete webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unathorized role:
              value:
                message: Only organization admins (or higher) can create an organization webhook
            zeplin app error:
              value:
                message: User cannot delete webhooks created by Zeplin apps
    projectWebhookNotFound:
      description: Webhook not found response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Project not found:
              value:
                message: Project not found
            webhook not found:
              value:
                message: Webhook not found
    cannotAccessProjectWebhook:
      description: User cannot access project webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Organization project webhook:
              value:
                message: Only organization editor (or higher) can access project webhooks
            Personal project webhook:
              value:
                message: Only owner of the project can access webhooks
    cannotUpdateOrganizationWebhook:
      description: User cannot update webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unathorized role:
              value:
                message: Only organization admins (or higher) can update an organization webhook
            zeplin app error:
              value:
                message: User cannot update webhooks created by Zeplin apps
    unprocessableEntityCreateProjectWebhook:
      description: Cannot create a project webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            URL unhealthy with status active:
              value:
                message: Cannot create a webhook with active status because provided URL is unhealthy
            Project is archived:
              value:
                message: Project is archived
            Not a member:
              value:
                message: User is not a member of the project
    notAProjectMemberOrArchived:
      description: Not a project member or project archived
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Not a member:
              value:
                message: User is not a member of the project
            Project is archived:
              value:
                message: Project is archived
    styleguideNotFound:
      description: Styleguide not found response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Styleguide not found response:
              value:
                message: Styleguide not found
    projectNotFound:
      description: Project not found response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Project not found response:
              value:
                message: Project not found
    cannotGetWebhook:
      description: User cannot get webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            User cannot get webhook:
              value:
                message: Only organization admins (or higher) can create an organization webhook
    unprocessableEntityUpdateWebhook:
      description: Cannot update webhook because URL unhealthy
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Cannot update status to active:
              value:
                message: Cannot update webhook to have active status because the URL "http://unhealthy.somewhere.io" is unhealthy
            Cannot update URL when status active:
              value:
                message: Cannot update webhook's URL because an active webhook's URL cannot be unhealthy
            styleguide_id not found:
              value:
                message: 5ea974b04c1dd72d978e1e63 in styleguide_ids is not found
            styleguide_ids not found:
              value:
                message: 5ea975058dfb1930747cd82e, 5ea974fc362dfe6dcba214ac and 5ea974b04c1dd72d978e1e63 in styleguide_ids are not found
            project_id not found:
              value:
                message: 5ea974b04c1dd72d978e1e63 in project_ids is not found
            project_ids not found:
              value:
                message: 5ea975058dfb1930747cd82e, 5ea974fc362dfe6dcba214ac and 5ea974b04c1dd72d978e1e63 in project_ids are not found
    unprocessableEntityUpdateStyleguideWebhook:
      description: Styleguide archived, not a member or status active with unhealthy URL
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Styleguide is archived:
              value:
                message: Styleguide is archived
            Not a member:
              value:
                message: User is not a member of the styleguide
            Cannot make status active:
              value:
                message: Cannot update webhook to have active status because the URL "https://unhealthy.com" is unhealthy
            Cannot update URL:
              value:
                message: Cannot update webhook's URL because an active webhook's URL cannot be unhealthy
    forbiddenCreateStyleguideWebhook:
      description: User cannot create a styleguide webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Cannot access webhook of organization styleguide:
              value:
                message: Only organization editor (or higher) can access styleguide webhooks
            Cannot access webhook of personal styleguide:
              value:
                message: Only owner of the styleguide can access webhooks
            Zeplin app error:
              value:
                message: This zeplin app cannot create webhook. User needs to re-authorize the app to create webhook
    cannotDeleteUserWebhook:
      description: User cannot delete webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            User cannot delete webhook:
              value:
                message: User cannot delete webhooks created by Zeplin apps
    cannotUpdateUserWebhook:
      description: User cannot update webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            User cannot update webhook:
              value:
                message: User cannot update webhooks created by Zeplin apps
    cannotUpdateProjectWebhook:
      description: User cannot update project webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Organization project webhook:
              value:
                message: Only organization editor (or higher) can access project webhooks
            Personal project webhook:
              value:
                message: Only owner of the project can access webhooks
            Cannot update app webhook:
              value:
                message: User cannot update webhooks created by Zeplin apps
    forbiddenCreateProjectWebhook:
      description: User cannot create a project webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Cannot access webhook of organization project:
              value:
                message: Only organization editor (or higher) can access project webhooks
            Cannot access webhook of personal project:
              value:
                message: Only owner of the project can access webhooks
            Zeplin app error:
              value:
                message: This zeplin app cannot create webhook. User needs to re-authorize the app to create webhook
    notAStyleguideMemberOrArchived:
      description: Not a styleguide member or styleguide archived
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Not a member:
              value:
                message: User is not a member of the styleguide
            Styleguide is archived:
              value:
                message: Styleguide is archived
    userWebhookNotFound:
      description: Webhook not found response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Webhook not found response:
              value:
                message: Webhook not found
    cannotUpdateStyleguideWebhook:
      description: User cannot update styleguide webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Organization styleguide webhook:
              value:
                message: Only organization editor (or higher) can access styleguide webhooks
            Personal styleguide webhook:
              value:
                message: Only owner of the styleguide can access webhooks
            Cannot update app webhook:
              value:
                message: User cannot update webhooks created by Zeplin apps
    cannotDeleteProjectWebhook:
      description: User cannot access project webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Organization project webhook:
              value:
                message: Only organization editor (or higher) can access project webhooks
            Personal project webhook:
              value:
                message: Only owner of the project can access webhooks
            Cannot delete app webhook:
              value:
                message: User cannot delete webhooks created by Zeplin apps
    cannotCreateOrganizationWebhook:
      description: User cannot create webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unathorized role:
              value:
                message: Only organization admins (or higher) can create an organization webhook
            zeplin app error:
              value:
                message: This zeplin app cannot create webhook. User needs to re-authorize the app to create webhook
    unprocessableEntityCreateWebhook:
      description: Cannot create active webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            URL unhealthy with status active:
              value:
                message: Cannot create a webhook with active status because provided URL is unhealthy
            styleguide_id not found:
              value:
                message: 5ea974b04c1dd72d978e1e63 in styleguide_ids is not found
            styleguide_ids not found:
              value:
                message: 5ea975058dfb1930747cd82e, 5ea974fc362dfe6dcba214ac and 5ea974b04c1dd72d978e1e63 in styleguide_ids are not found
            project_id not found:
              value:
                message: 5ea974b04c1dd72d978e1e63 in project_ids is not found
            project_ids not found:
              value:
                message: 5ea975058dfb1930747cd82e, 5ea974fc362dfe6dcba214ac and 5ea974b04c1dd72d978e1e63 in project_ids are not found
    noContent:
      description: Successful response
    styleguideWebhookNotFound:
      description: Webhook not found response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Styleguide not found:
              value:
                message: Styleguide not found
            webhook not found:
              value:
                message: Webhook not found
    cannotCreateUserWebhook:
      description: User cannot create webhook
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            User cannot create webhook:
              value:
                message: This zeplin app cannot create webhook. User needs to re-authorize the app to create webhook
    unprocessableEntityUpdateProjectWebhook:
      description: Project archived, not a member or status active with unhealthy URL
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Project is archived:
              value:
                message: Project is archived
            Not a member:
              value:
                message: User is not a member of the project
            Cannot make status active:
              value:
                message: Cannot update webhook to have active status because the URL "https://unhealthy.com" is unhealthy
            Cannot update URL:
              value:
                message: Cannot update webhook's URL because an active webhook's URL cannot be unhealthy
    organizationWebhookNotFound:
      description: Webhook not found response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            organization not found:
              value:
                message: Organization not found
            webhook not found:
              value:
                message: Webhook not found
    organizationNotFound:
      description: Organization not found response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            Organization not found response:
              value:
                message: Organization not found
  parameters:
    webhook_status:
      name: status
      in: query
      description: Filter by webhook status
      required: false
      schema:
        $ref: '#/components/schemas/WebhookStatusEnum'
    organization_id:
      name: organization_id
      in: path
      description: Organization id
      required: true
      schema:
        type: string
        pattern: /^[0-9a-f]{24}$/i
    limit:
      name: limit
      in: query
      description: Pagination limit
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    offset:
      name: offset
      in: query
      description: Pagination offset
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    project_id:
      name: project_id
      in: path
      description: Project id
      required: true
      schema:
        type: string
        pattern: /^[0-9a-f]{24}$/i
    url_health:
      name: url_health
      in: query
      description: Filter by health of webhook's URL
      required: false
      schema:
        $ref: '#/components/schemas/WebhookHealthEnum'
    webhook_id:
      name: webhook_id
      in: path
      description: Webhook id
      required: true
      schema:
        type: string
        pattern: /^[0-9a-f]{24}$/i
    styleguide_id:
      name: styleguide_id
      in: path
      description: Styleguide id
      required: true
      schema:
        type: string
        pattern: /^[0-9a-f]{24}$/i
  examples:
    user:
      summary: User
      value:
        id: 5d9caaecb4a3fa9bc9718686
        email: 5d9caaecb4a3fa9bc9718686@user.zeplin.io
        username: zozo
        emotar: 🍎
        avatar: http://placekitten.com/200/300
        last_seen: 1616739240
    zeplinApplication:
      summary: Zeplin Application
      value:
        id: 5dbad85a76ea51c1f35b6f69
        name: My App
        description: Simple app
        website: https://zeplin.io/
        logo: http://placekitten.com/32/32
    webhook:
      summary: Webhook
      value:
        id: 5dbad85a76ea51c1f35b6f69
        name: my lovely hook
        status: active
        created: 1586852836
        created_by:
          id: 5d9caaecb4a3fa9bc9718686
          email: 5d9caaecb4a3fa9bc9718686@user.zeplin.
        updated: 1586852836
        updated_by:
          id: 5d9caaecb4a3fa9bc9718686
          email: 5d9caaecb4a3fa9bc9718686@user.zeplin.io
        url: https://www.example.com/base
        url_health: healthy
        events:
        - '*'
        project_ids:
        - '*'
        styleguide_ids:
        - '*'
    error:
      summary: Error
      value:
        message: Project is not found
    styleguideWebhook:
      summary: Styleguide Webhook
      value:
        id: 5dbad85a76ea51c1f35b6f69
        name: my lovely hook
        status: active
        created: 1586852836
        created_by:
          id: 5d9caaecb4a3fa9bc9718686
          email: 5d9caaecb4a3fa9bc9718686@user.zeplin.io
        updated: 1586852836
        updated_by:
          id: 5d9caaecb4a3fa9bc9718686
          email: 5d9caaecb4a3fa9bc9718686@user.zeplin.io
        url: https://www.example.com/base
        url_health: healthy
        events:
        - styleguide.color
    projectWebhook:
      summary: Project Webhook
      value:
        id: 5dbad85a76ea51c1f35b6f69
        name: my lovely hook
        status: active
        created: 1586852836
        created_by:
          id: 5d9caaecb4a3fa9bc9718686
          email: 5d9caaecb4a3fa9bc9718686@user.zeplin.io
        updated: 1586852836
        updated_by:
          id: 5d9caaecb4a3fa9bc9718686
          email: 5d9caaecb4a3fa9bc9718686@user.zeplin.io
        url: https://www.example.com/base
        url_health: healthy
        events:
        - project.screen
    me:
      summary: My user
      value:
        id: 5d9caaecb4a3fa9bc9718686
        email: zo@zeplin.io
        username: zozo
        emotar: 🍎
        avatar: http://placekitten.com/200/300
        last_seen: 1616739240
    entityReference:
      summary: Object Reference
      value:
        id: 5dbad85a76ea51c1f35b6f69
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /v1/oauth/authorize
          tokenUrl: /v1/oauth/token
          refreshUrl: /v1/oauth/token
          scopes: {}
    PersonalAccessToken:
      type: http
      scheme: bearer
      bearerFormat: JWT