Figma Webhooks API

openapi: 3.1.0
info:
  title: Figma Activity Logs Webhooks API
  version: 0.21.0
  description: 'Figma allows designers to create and prototype their digital experiences -

    together in real-time and in one place - helping them turn their ideas and

    visions into products, faster. Figma''s mission is to make design

    accessible to everyone. The Figma API is one of the ways we aim to do that.'
  termsOfService: https://www.figma.com/developer-terms/
  contact:
    email: support@figma.com
servers:
- url: https://api.figma.com
  description: Figma Production API Server
tags:
- name: Webhooks
  description: Operations for managing webhook subscriptions and notifications
paths:
  /v2/teams/{team_id}/webhooks:
    get:
      tags:
      - Webhooks
      summary: Figma Get Team Webhooks
      security:
      - PersonalAccessToken: []
      - OAuth2:
        - files:read
      description: Returns all webhooks registered under the specified team.
      operationId: getTeamWebhooks
      x-microcks-operation:
        dispatcher: URI_PARTS
        dispatcherRules: team_id
        defaultResponse: GetTeamWebhooksSuccessExample
      parameters:
      - $ref: '#/components/parameters/TeamIdPath'
      responses:
        '200':
          $ref: '#/components/responses/GetTeamWebhooksResponse'
        '403':
          $ref: '#/components/responses/ForbiddenErrorResponse'
        '404':
          $ref: '#/components/responses/NotFoundErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
components:
  schemas:
    ErrorResponsePayload:
      type: object
      description: A response indicating an error occurred.
      properties:
        status:
          type: number
          description: Status code
          example: 42.5
        err:
          type: string
          description: A string describing the error
          example: example_value
      required:
      - status
      - err
    WebhookV2Event:
      type: string
      description: The event type that triggers the webhook.
      enum:
      - FILE_UPDATE
      - FILE_DELETE
      - FILE_VERSION_UPDATE
      - LIBRARY_PUBLISH
      - FILE_COMMENT
      example: FILE_UPDATE
    WebhookV2:
      type: object
      description: A description of an HTTP webhook (from Figma back to your application)
      properties:
        id:
          type: string
          description: The ID of the webhook
          example: abc123
        event_type:
          $ref: '#/components/schemas/WebhookV2Event'
        team_id:
          type: string
          description: The team id you are subscribed to for updates
          example: '500123'
        status:
          $ref: '#/components/schemas/WebhookV2Status'
        client_id:
          type:
          - string
          - 'null'
          description: The client ID of the OAuth application that registered this webhook, if any
          example: '500123'
        passcode:
          type: string
          description: The passcode that will be passed back to the webhook endpoint
          example: example_value
        endpoint:
          type: string
          description: The endpoint that will be hit when the webhook is triggered
          example: example_value
        description:
          type:
          - string
          - 'null'
          description: Optional user-provided description or name for the webhook. This is provided to help make maintaining a number of webhooks more convenient. Max length 140 characters.
          example: A sample description.
      required:
      - id
      - event_type
      - team_id
      - status
      - client_id
      - passcode
      - endpoint
      - description
      example:
        id: webhook_abc123xyz789
        event_type: FILE_UPDATE
        team_id: team_12345678
        status: ACTIVE
        client_id: oauth_client_xyz
        passcode: secret_passcode_123
        endpoint: https://api.myapp.com/figma/webhooks
        description: Webhook for design file updates
    TooManyRequestsError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 429
        required:
        - status
      example:
        status: 429
        err: Rate limit exceeded. Please wait before retrying.
    NotFoundError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 404
        required:
        - status
      example:
        status: 404
        err: Team not found
    GetTeamWebhooksResponseBody:
      type: object
      description: Successful response containing team webhooks.
      properties:
        webhooks:
          type: array
          description: An array of webhooks.
          items:
            $ref: '#/components/schemas/WebhookV2'
          example: []
      required:
      - webhooks
      example:
        webhooks:
        - id: webhook_abc123xyz789
          event_type: FILE_UPDATE
          team_id: team_12345678
          status: ACTIVE
          client_id: oauth_client_xyz
          passcode: secret_passcode_123
          endpoint: https://api.myapp.com/figma/webhooks
          description: Webhook for design file updates
        - id: webhook_def456uvw012
          event_type: FILE_COMMENT
          team_id: team_12345678
          status: PAUSED
          client_id: null
          passcode: another_passcode_456
          endpoint: https://api.myapp.com/figma/comments
          description: null
    InternalServerError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 500
        required:
        - status
      example:
        status: 500
        err: Internal server error
    WebhookV2Status:
      type: string
      description: The current status of the webhook.
      enum:
      - ACTIVE
      - PAUSED
      example: ACTIVE
    ForbiddenError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 403
        required:
        - status
      example:
        status: 403
        err: Access denied. You do not have permission to access this team's webhooks.
  responses:
    InternalServerErrorResponse:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
          examples:
            InternalServerErrorExample:
              summary: Internal server error
              value:
                status: 500
                err: Internal server error
    TooManyRequestsErrorResponse:
      description: In some cases API requests may be throttled or rate limited. Please wait a while before attempting the request again (typically a minute).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TooManyRequestsError'
          examples:
            TooManyRequestsExample:
              summary: Rate limit exceeded error
              value:
                status: 429
                err: Rate limit exceeded. Please wait before retrying.
    ForbiddenErrorResponse:
      description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ForbiddenError'
          examples:
            ForbiddenExample:
              summary: Access denied error
              value:
                status: 403
                err: Access denied. You do not have permission to access this team's webhooks.
    GetTeamWebhooksResponse:
      description: Response from the GET /v2/teams/{team_id}/webhooks endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetTeamWebhooksResponseBody'
          examples:
            GetTeamWebhooksSuccessExample:
              summary: Successful team webhooks response
              value:
                webhooks:
                - id: webhook_abc123xyz789
                  event_type: FILE_UPDATE
                  team_id: team_12345678
                  status: ACTIVE
                  client_id: oauth_client_xyz
                  passcode: secret_passcode_123
                  endpoint: https://api.myapp.com/figma/webhooks
                  description: Webhook for design file updates
                - id: webhook_def456uvw012
                  event_type: FILE_COMMENT
                  team_id: team_12345678
                  status: PAUSED
                  client_id: null
                  passcode: another_passcode_456
                  endpoint: https://api.myapp.com/figma/comments
                  description: null
    NotFoundErrorResponse:
      description: The requested file or resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
          examples:
            NotFoundExample:
              summary: Team not found error
              value:
                status: 404
                err: Team not found
  parameters:
    TeamIdPath:
      name: team_id
      in: path
      description: ID of team to get webhooks for
      required: true
      schema:
        type: string
      example: team_12345678
  securitySchemes:
    OrgOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.figma.com/oauth
          tokenUrl: https://api.figma.com/v1/oauth/token
          scopes:
            org:activity_log_read: Read organization activity logs