Figma Webhooks

asyncapi: 2.6.0
info:
  title: Figma Webhooks
  description: >-
    Figma Webhooks allow applications to receive real-time notifications when
    events occur in Figma files and projects. Webhooks are configured at the
    team level and send HTTP POST requests with JSON payloads to a specified
    endpoint URL. Supported events include file updates, comments, library
    publish changes, and version history updates. Webhooks use a passcode
    for payload verification.
  version: '2.0.0'
  contact:
    name: Figma Developer Support
    url: https://www.figma.com/developers
    email: support@figma.com
  license:
    name: Figma Developer Terms
    url: https://www.figma.com/developer-terms/
  externalDocs:
    description: Figma Webhooks Documentation
    url: https://developers.figma.com/docs/rest-api/webhooks/
servers:
  webhook-receiver:
    url: '{webhookUrl}'
    protocol: https
    description: >-
      Your webhook receiver endpoint. Figma sends POST requests to this URL
      when subscribed events occur on the specified team. The endpoint must
      respond with a 200-level status code within 10 seconds.
    variables:
      webhookUrl:
        description: >-
          The URL configured to receive webhook deliveries. This is set when
          creating or updating a webhook via the Figma REST API.
    security:
      - passcodeVerification: []
channels:
  /webhook:
    description: >-
      The endpoint that receives all Figma webhook event deliveries. The
      specific event type is identified by the event_type field in the
      payload. Figma webhooks are team-scoped and can subscribe to specific
      event types.
    publish:
      operationId: receiveFigmaWebhookEvent
      summary: Receive a Figma webhook event
      description: >-
        Figma delivers webhook events as HTTP POST requests with JSON payloads.
        Each delivery includes a passcode field that matches the passcode
        configured when the webhook was created, which can be used to verify
        authenticity. If a webhook endpoint fails to respond with a 2xx status
        code, Figma will retry delivery with exponential backoff.
      bindings:
        http:
          type: request
          method: POST
          headers:
            type: object
            properties:
              Content-Type:
                type: string
                enum:
                  - application/json
                description: The content type of the webhook payload.
      message:
        oneOf:
          - $ref: '#/components/messages/ping'
          - $ref: '#/components/messages/file_update'
          - $ref: '#/components/messages/file_version_update'
          - $ref: '#/components/messages/file_delete'
          - $ref: '#/components/messages/file_comment'
          - $ref: '#/components/messages/library_publish'
components:
  securitySchemes:
    passcodeVerification:
      type: userPassword
      description: >-
        Figma webhook payloads include a passcode field that matches the
        passcode you specified when creating the webhook. Compare this value
        to verify the payload originated from Figma.
  messages:
    ping:
      name: ping
      title: Ping Event
      summary: >-
        Test event sent when a webhook is first created to verify the endpoint
        is reachable.
      description: >-
        The PING event is sent immediately when a new webhook is created via
        the POST /v2/webhooks endpoint. This event confirms that your endpoint
        is reachable and can process Figma webhook payloads. The webhook will
        be set to ACTIVE status if the ping succeeds.
      payload:
        $ref: '#/components/schemas/PingEvent'

    file_update:
      name: file_update
      title: File Update Event
      summary: >-
        Triggered when a file in the team is saved or modified.
      description: >-
        The FILE_UPDATE event fires whenever a Figma file within the subscribed
        team is modified and saved. This includes changes to the document tree,
        styles, components, and other file properties. Multiple rapid saves
        may be batched into a single webhook delivery.
      payload:
        $ref: '#/components/schemas/FileUpdateEvent'

    file_version_update:
      name: file_version_update
      title: File Version Update Event
      summary: >-
        Triggered when a named version is created in the file's version history.
      description: >-
        The FILE_VERSION_UPDATE event fires when a user creates a named version
        in a file's version history. This does not fire for auto-saved versions.
      payload:
        $ref: '#/components/schemas/FileVersionUpdateEvent'

    file_delete:
      name: file_delete
      title: File Delete Event
      summary: >-
        Triggered when a file in the team is deleted.
      description: >-
        The FILE_DELETE event fires when a Figma file within the subscribed
        team is permanently deleted. This event is not triggered when a file
        is moved to trash but only when it is permanently removed.
      payload:
        $ref: '#/components/schemas/FileDeleteEvent'

    file_comment:
      name: file_comment
      title: File Comment Event
      summary: >-
        Triggered when a new comment is posted on a file.
      description: >-
        The FILE_COMMENT event fires when a user posts a new comment on a
        Figma file within the subscribed team. This includes both top-level
        comments and replies. The payload includes the comment text, author,
        and location metadata.
      payload:
        $ref: '#/components/schemas/FileCommentEvent'

    library_publish:
      name: library_publish
      title: Library Publish Event
      summary: >-
        Triggered when a library file publishes new components or styles.
      description: >-
        The LIBRARY_PUBLISH event fires when a library file within the
        subscribed team publishes updates to its components, component sets,
        or styles. The payload includes lists of created, modified, and
        deleted library items.
      payload:
        $ref: '#/components/schemas/LibraryPublishEvent'

  schemas:
    BaseEvent:
      type: object
      description: >-
        Common properties shared by all Figma webhook event payloads.
      required:
        - event_type
        - passcode
        - timestamp
        - webhook_id
      properties:
        event_type:
          type: string
          description: The type of event that triggered this webhook delivery.
          enum:
            - PING
            - FILE_UPDATE
            - FILE_VERSION_UPDATE
            - FILE_DELETE
            - FILE_COMMENT
            - LIBRARY_PUBLISH
        passcode:
          type: string
          description: >-
            The passcode specified when the webhook was created. Use this to
            verify the payload originated from Figma.
        timestamp:
          type: string
          format: date-time
          description: The UTC ISO 8601 time when the event occurred.
        webhook_id:
          type: string
          description: The unique identifier of the webhook that generated this delivery.

    PingEvent:
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          description: >-
            Sent when a webhook is first created to verify the endpoint is
            reachable. Contains no additional fields beyond the base event.
          properties:
            event_type:
              type: string
              enum:
                - PING

    FileUpdateEvent:
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          description: >-
            Delivered when a file within the subscribed team is saved.
          required:
            - file_key
            - file_name
            - triggered_by
          properties:
            event_type:
              type: string
              enum:
                - FILE_UPDATE
            file_key:
              type: string
              description: The key of the file that was updated.
            file_name:
              type: string
              description: The name of the file at the time of the event.
            triggered_by:
              $ref: '#/components/schemas/WebhookUser'

    FileVersionUpdateEvent:
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          description: >-
            Delivered when a named version is created in the version history.
          required:
            - file_key
            - file_name
            - triggered_by
          properties:
            event_type:
              type: string
              enum:
                - FILE_VERSION_UPDATE
            file_key:
              type: string
              description: The key of the file where the version was created.
            file_name:
              type: string
              description: The name of the file.
            version_id:
              type: string
              description: The ID of the newly created version.
            label:
              type: string
              description: The label given to the new version.
            description:
              type: string
              description: The description of the new version.
            triggered_by:
              $ref: '#/components/schemas/WebhookUser'

    FileDeleteEvent:
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          description: >-
            Delivered when a file within the subscribed team is deleted.
          required:
            - file_key
            - file_name
            - triggered_by
          properties:
            event_type:
              type: string
              enum:
                - FILE_DELETE
            file_key:
              type: string
              description: The key of the file that was deleted.
            file_name:
              type: string
              description: The name of the file at the time of deletion.
            triggered_by:
              $ref: '#/components/schemas/WebhookUser'

    FileCommentEvent:
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          description: >-
            Delivered when a comment is posted on a file within the subscribed team.
          required:
            - file_key
            - file_name
            - comment
            - triggered_by
          properties:
            event_type:
              type: string
              enum:
                - FILE_COMMENT
            file_key:
              type: string
              description: The key of the file where the comment was posted.
            file_name:
              type: string
              description: The name of the file.
            comment:
              type: array
              description: >-
                An array of comment objects representing the new comment and
                any mentions within the comment.
              items:
                $ref: '#/components/schemas/WebhookComment'
            comment_id:
              type: string
              description: The ID of the comment that was posted.
            parent_id:
              type: string
              description: >-
                The ID of the parent comment if this is a reply, otherwise null.
            triggered_by:
              $ref: '#/components/schemas/WebhookUser'

    LibraryPublishEvent:
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
        - type: object
          description: >-
            Delivered when a library file publishes new or updated components,
            component sets, or styles.
          required:
            - file_key
            - file_name
            - triggered_by
          properties:
            event_type:
              type: string
              enum:
                - LIBRARY_PUBLISH
            file_key:
              type: string
              description: The key of the library file that was published.
            file_name:
              type: string
              description: The name of the library file.
            description:
              type: string
              description: The publish description entered by the user.
            created_components:
              type: array
              description: Components that were newly published.
              items:
                $ref: '#/components/schemas/LibraryItem'
            modified_components:
              type: array
              description: Components that were modified and republished.
              items:
                $ref: '#/components/schemas/LibraryItem'
            deleted_components:
              type: array
              description: Components that were unpublished.
              items:
                $ref: '#/components/schemas/LibraryItem'
            created_styles:
              type: array
              description: Styles that were newly published.
              items:
                $ref: '#/components/schemas/LibraryItem'
            modified_styles:
              type: array
              description: Styles that were modified and republished.
              items:
                $ref: '#/components/schemas/LibraryItem'
            deleted_styles:
              type: array
              description: Styles that were unpublished.
              items:
                $ref: '#/components/schemas/LibraryItem'
            triggered_by:
              $ref: '#/components/schemas/WebhookUser'

    WebhookUser:
      type: object
      description: >-
        A simplified user object included in webhook payloads identifying
        the user who triggered the event.
      required:
        - id
        - handle
      properties:
        id:
          type: string
          description: The unique stable ID of the user.
        handle:
          type: string
          description: The display name of the user.
        img_url:
          type: string
          format: uri
          description: URL to the user's profile image.

    WebhookComment:
      type: object
      description: >-
        A comment segment within a webhook FILE_COMMENT payload. Comment text
        is split into segments to support mentions.
      properties:
        text:
          type: string
          description: The text content of the comment segment.
        mention:
          type: string
          description: >-
            If this segment is a mention, this is the user ID of the mentioned
            user.

    LibraryItem:
      type: object
      description: >-
        A library item (component or style) referenced in a LIBRARY_PUBLISH
        webhook payload.
      required:
        - key
        - name
      properties:
        key:
          type: string
          description: The globally unique key of the library item.
        name:
          type: string
          description: The name of the library item.