Box

Box Webhooks API

Webhooks allow you to monitor Box content for events, and receive notifications to a URL of your choice when they occur. For example, a workflow may include waiting for a file to be downloaded to delete a shared link.

Documentation GitHub OpenAPI

Documentation

https://developer.box.com/reference/get-authorize

https://developer.box.com/reference/post-oauth2-token

https://developer.box.com/reference/post-files-id-copy

https://developer.box.com/reference/post-file-requests-id-copy

https://developer.box.com/reference/post-folders-id-copy

https://developer.box.com/reference/post-folder-locks

https://developer.box.com/reference/post-metadata-templates-schema

https://developer.box.com/reference/post-metadata-cascade-policies

https://developer.box.com/reference/post-metadata-queries-execute-read

https://developer.box.com/reference/post-comments

https://developer.box.com/reference/post-collaborations

https://developer.box.com/reference/post-tasks

https://developer.box.com/reference/post-task-assignments

https://developer.box.com/reference/put-files-id--add-shared-link

https://developer.box.com/reference/put-folders-id--add-shared-link

https://developer.box.com/reference/post-web-links

https://developer.box.com/reference/put-web-links-id--add-shared-link

https://developer.box.com/reference/post-users

https://developer.box.com/reference/post-invites

https://developer.box.com/reference/post-groups

https://developer.box.com/reference/post-group-memberships

https://developer.box.com/reference/post-webhooks

https://developer.box.com/reference/post-files-id-metadata-global-boxSkillsCards

https://developer.box.com/reference/options-events

https://developer.box.com/reference/get-collections-id

https://developer.box.com/reference/get-recent-items

https://developer.box.com/reference/post-retention-policies

https://developer.box.com/reference/post-retention-policy-assignments

https://developer.box.com/reference/post-legal-hold-policies

https://developer.box.com/reference/post-legal-hold-policy-assignments

https://developer.box.com/reference/get-file-version-retentions-id

https://developer.box.com/reference/get-file-version-legal-holds-id

https://developer.box.com/reference/post-shield-information-barriers-change-status

https://developer.box.com/reference/post-shield-information-barrier-reports

https://developer.box.com/reference/post-shield-information-barrier-segments

https://developer.box.com/reference/post-shield-information-barrier-segment-members

https://developer.box.com/reference/post-shield-information-barrier-segment-restrictions

https://developer.box.com/reference/get-device-pinners-id

https://developer.box.com/reference/post-terms-of-services

https://developer.box.com/reference/post-terms-of-service-user-statuses

https://developer.box.com/reference/post-collaboration-whitelist-entries

https://developer.box.com/

Specifications

https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/openapi/box-webhooks-api-openapi.yml

Other Resources

https://raw.githubusercontent.com/api-evangelist/box/refs/heads/main/graphql/box-graphql.md

OpenAPI Specification

openapi: 3.1.0
info:
  version: "1.0"
  title: Box Authorize Authorization Webhooks API
  description: Needs a description.
tags:
- name: Webhooks
  description: 'Webhooks allow you to monitor Box content for events,

    and receive notifications to a URL of your choice when they occur.

    For example, a workflow may include waiting

    for a file to be downloaded to delete a shared link.'
  x-box-tag: webhooks
paths:
  /webhooks:
    get:
      operationId: get_webhooks
      summary: Box List all webhooks
      tags:
      - Webhooks
      x-box-tag: webhooks
      description: 'Returns all defined webhooks for the requesting application.


        This API only returns webhooks that are applied to files or folders that are

        owned by the authenticated user. This means that an admin can not see webhooks

        created by a service account unless the admin has access to those folders, and

        vice versa.'
      parameters:
      - name: marker
        description: 'Defines the position marker at which to begin returning results. This is

          used when paginating using marker-based pagination.


          This requires `usemarker` to be set to `true`.'
        in: query
        required: false
        example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
        schema:
          type: string
      - name: limit
        description: The maximum number of items to return per page.
        in: query
        required: false
        example: 1000
        schema:
          type: integer
          format: int64
          maximum: 1000
      responses:
        '200':
          description: Returns a list of webhooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhooks'
        '403':
          description: 'Returns an error if the application does not

            have the permission to manage webhooks.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    post:
      operationId: post_webhooks
      summary: Box Create webhook
      tags:
      - Webhooks
      x-box-tag: webhooks
      description: Creates a webhook.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - target
              - triggers
              - address
              properties:
                target:
                  type: object
                  description: The item that will trigger the webhook
                  properties:
                    id:
                      description: The ID of the item to trigger a webhook
                      type: string
                      example: '1231232'
                    type:
                      description: The type of item to trigger a webhook
                      type: string
                      example: file
                      enum:
                      - file
                      - folder
                address:
                  type: string
                  example: https://example.com/webhooks
                  description: The URL that is notified by this webhook
                triggers:
                  type: array
                  example:
                  - FILE.UPLOADED
                  description: 'An array of event names that this webhook is

                    to be triggered for'
                  items:
                    title: Webhook Trigger
                    example: FILE.UPLOADED
                    type: string
                    description: The event name that triggered this webhook
                    enum:
                    - FILE.UPLOADED
                    - FILE.PREVIEWED
                    - FILE.DOWNLOADED
                    - FILE.TRASHED
                    - FILE.DELETED
                    - FILE.RESTORED
                    - FILE.COPIED
                    - FILE.MOVED
                    - FILE.LOCKED
                    - FILE.UNLOCKED
                    - FILE.RENAMED
                    - COMMENT.CREATED
                    - COMMENT.UPDATED
                    - COMMENT.DELETED
                    - TASK_ASSIGNMENT.CREATED
                    - TASK_ASSIGNMENT.UPDATED
                    - METADATA_INSTANCE.CREATED
                    - METADATA_INSTANCE.UPDATED
                    - METADATA_INSTANCE.DELETED
                    - FOLDER.CREATED
                    - FOLDER.RENAMED
                    - FOLDER.DOWNLOADED
                    - FOLDER.RESTORED
                    - FOLDER.DELETED
                    - FOLDER.COPIED
                    - FOLDER.MOVED
                    - FOLDER.TRASHED
                    - WEBHOOK.DELETED
                    - COLLABORATION.CREATED
                    - COLLABORATION.ACCEPTED
                    - COLLABORATION.REJECTED
                    - COLLABORATION.REMOVED
                    - COLLABORATION.UPDATED
                    - SHARED_LINK.DELETED
                    - SHARED_LINK.CREATED
                    - SHARED_LINK.UPDATED
                    - SIGN_REQUEST.COMPLETED
                    - SIGN_REQUEST.DECLINED
                    - SIGN_REQUEST.EXPIRED
                    - SIGN_REQUEST.SIGNER_EMAIL_BOUNCED
      responses:
        '201':
          description: Returns the new webhook object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: 'Returns an error if the parameters were

            incorrect.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'Returns an error if the application does not

            have the permission to manage webhooks.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error if the target item could

            not be found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: 'Returns an error if the a webhook for this

            combination of target, application, and user

            already exists.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
  /webhooks/{webhook_id}:
    get:
      operationId: get_webhooks_id
      tags:
      - Webhooks
      x-box-tag: webhooks
      summary: Box Get webhook
      description: Retrieves a specific webhook
      parameters:
      - name: webhook_id
        description: The ID of the webhook.
        example: '3321123'
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns a webhook object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '403':
          description: 'Returns an error if the application does not

            have the permission to manage webhooks.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns an error if the webhook could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    put:
      operationId: put_webhooks_id
      summary: Box Update webhook
      tags:
      - Webhooks
      x-box-tag: webhooks
      description: Updates a webhook.
      parameters:
      - name: webhook_id
        description: The ID of the webhook.
        example: '3321123'
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                target:
                  type: object
                  description: The item that will trigger the webhook
                  properties:
                    id:
                      description: The ID of the item to trigger a webhook
                      type: string
                      example: '1231232'
                    type:
                      description: The type of item to trigger a webhook
                      type: string
                      example: file
                      enum:
                      - file
                      - folder
                address:
                  type: string
                  example: https://example.com/webhooks
                  description: The URL that is notified by this webhook
                triggers:
                  type: array
                  example:
                  - FILE.UPLOADED
                  description: 'An array of event names that this webhook is

                    to be triggered for'
                  items:
                    title: Webhook Trigger
                    example: FILE.UPLOADED
                    type: string
                    description: The event name that triggered this webhook
                    enum:
                    - FILE.UPLOADED
                    - FILE.PREVIEWED
                    - FILE.DOWNLOADED
                    - FILE.TRASHED
                    - FILE.DELETED
                    - FILE.RESTORED
                    - FILE.COPIED
                    - FILE.MOVED
                    - FILE.LOCKED
                    - FILE.UNLOCKED
                    - FILE.RENAMED
                    - COMMENT.CREATED
                    - COMMENT.UPDATED
                    - COMMENT.DELETED
                    - TASK_ASSIGNMENT.CREATED
                    - TASK_ASSIGNMENT.UPDATED
                    - METADATA_INSTANCE.CREATED
                    - METADATA_INSTANCE.UPDATED
                    - METADATA_INSTANCE.DELETED
                    - FOLDER.CREATED
                    - FOLDER.RENAMED
                    - FOLDER.DOWNLOADED
                    - FOLDER.RESTORED
                    - FOLDER.DELETED
                    - FOLDER.COPIED
                    - FOLDER.MOVED
                    - FOLDER.TRASHED
                    - WEBHOOK.DELETED
                    - COLLABORATION.CREATED
                    - COLLABORATION.ACCEPTED
                    - COLLABORATION.REJECTED
                    - COLLABORATION.REMOVED
                    - COLLABORATION.UPDATED
                    - SHARED_LINK.DELETED
                    - SHARED_LINK.CREATED
                    - SHARED_LINK.UPDATED
                    - SIGN_REQUEST.COMPLETED
                    - SIGN_REQUEST.DECLINED
                    - SIGN_REQUEST.EXPIRED
                    - SIGN_REQUEST.SIGNER_EMAIL_BOUNCED
      responses:
        '200':
          description: Returns the new webhook object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: 'Returns an error if the parameters were

            incorrect.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '403':
          description: 'Returns an error if the application does not

            have the permission to manage webhooks.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: 'Returns an error if the target item or webhook

            could not be found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '409':
          description: 'Returns an error if the a webhook for this

            combination of target, application, and user

            already exists.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
    delete:
      operationId: delete_webhooks_id
      summary: Box Remove webhook
      tags:
      - Webhooks
      x-box-tag: webhooks
      description: Deletes a webhook.
      parameters:
      - name: webhook_id
        description: The ID of the webhook.
        example: '3321123'
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: 'An empty response will be returned when the webhook

            was successfully deleted.'
        '403':
          description: 'Returns an error if the application does not

            have the permission to manage webhooks.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        '404':
          description: Returns an error if the webhook could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
        default:
          description: An unexpected client error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientError'
components:
  schemas:
    Webhooks:
      title: Webhooks
      type: object
      x-box-resource-id: webhooks
      x-box-tag: webhooks
      description: A list of webhooks.
      allOf:
      - type: object
        description: 'The part of an API response that describes marker

          based pagination'
        properties:
          limit:
            description: 'The limit that was used for these entries. This will be the same as the

              `limit` query parameter unless that value exceeded the maximum value

              allowed. The maximum value varies by API.'
            example: 1000
            type: integer
            format: int64
          next_marker:
            description: The marker for the start of the next page of results.
            example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii
            type: string
            nullable: true
          prev_marker:
            description: The marker for the start of the previous page of results.
            example: JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih
            type: string
            nullable: true
      - properties:
          entries:
            type: array
            description: A list of webhooks
            items:
              $ref: '#/components/schemas/Webhook--Mini'
    User--Base:
      title: User (Base)
      type: object
      x-box-resource-id: user--base
      x-box-tag: users
      x-box-variants:
      - base
      - mini
      - standard
      - full
      x-box-variant: base
      description: 'A mini representation of a user, used when

        nested within another resource.'
      required:
      - type
      - id
      properties:
        id:
          type: string
          description: The unique identifier for this user
          example: '11446498'
        type:
          type: string
          description: '`user`'
          example: user
          nullable: false
          enum:
          - user
    Webhook:
      title: Webhook
      type: object
      x-box-resource-id: webhook
      x-box-variant: standard
      x-box-tag: webhooks
      description: Represents a configured webhook.
      allOf:
      - $ref: '#/components/schemas/Webhook--Mini'
      - properties:
          created_by:
            allOf:
            - $ref: '#/components/schemas/User--Mini'
            - description: The user who created the webhook
          created_at:
            type: string
            format: date-time
            description: 'A timestamp identifying the time that

              the webhook was created.'
            example: '2012-12-12T10:53:43-08:00'
          address:
            type: string
            example: https://example.com/webhooks
            description: The URL that is notified by this webhook
          triggers:
            type: array
            example:
            - FILE.UPLOADED
            description: 'An array of event names that this webhook is

              to be triggered for'
            items:
              title: Webhook Trigger
              example: FILE.UPLOADED
              type: string
              description: The event name that triggered this webhook
              enum:
              - FILE.UPLOADED
              - FILE.PREVIEWED
              - FILE.DOWNLOADED
              - FILE.TRASHED
              - FILE.DELETED
              - FILE.RESTORED
              - FILE.COPIED
              - FILE.MOVED
              - FILE.LOCKED
              - FILE.UNLOCKED
              - FILE.RENAMED
              - COMMENT.CREATED
              - COMMENT.UPDATED
              - COMMENT.DELETED
              - TASK_ASSIGNMENT.CREATED
              - TASK_ASSIGNMENT.UPDATED
              - METADATA_INSTANCE.CREATED
              - METADATA_INSTANCE.UPDATED
              - METADATA_INSTANCE.DELETED
              - FOLDER.CREATED
              - FOLDER.RENAMED
              - FOLDER.DOWNLOADED
              - FOLDER.RESTORED
              - FOLDER.DELETED
              - FOLDER.COPIED
              - FOLDER.MOVED
              - FOLDER.TRASHED
              - WEBHOOK.DELETED
              - COLLABORATION.CREATED
              - COLLABORATION.ACCEPTED
              - COLLABORATION.REJECTED
              - COLLABORATION.REMOVED
              - COLLABORATION.UPDATED
              - SHARED_LINK.DELETED
              - SHARED_LINK.CREATED
              - SHARED_LINK.UPDATED
              - SIGN_REQUEST.COMPLETED
              - SIGN_REQUEST.DECLINED
              - SIGN_REQUEST.EXPIRED
              - SIGN_REQUEST.SIGNER_EMAIL_BOUNCED
    User--Mini:
      title: User (Mini)
      type: object
      x-box-resource-id: user--mini
      x-box-variant: mini
      description: 'A mini representation of a user, as can be returned when nested within other

        resources.'
      allOf:
      - $ref: '#/components/schemas/User--Base'
      - properties:
          name:
            type: string
            description: The display name of this user
            example: Aaron Levie
            maxLength: 50
            nullable: false
          login:
            type: string
            format: email
            description: The primary email address of this user
            example: ceo@example.com
            nullable: false
    Webhook--Mini:
      title: Webhook (Mini)
      type: object
      x-box-resource-id: webhook--mini
      x-box-tag: webhooks
      x-box-variants:
      - mini
      - standard
      x-box-variant: mini
      description: Represents a configured webhook.
      properties:
        id:
          type: string
          description: The unique identifier for this webhook.
          example: '11446498'
        type:
          type: string
          description: '`webhook`'
          example: webhook
          enum:
          - webhook
        target:
          type: object
          description: The item that will trigger the webhook
          properties:
            id:
              description: The ID of the item to trigger a webhook
              type: string
              example: '1231232'
            type:
              description: The type of item to trigger a webhook
              type: string
              example: file
              enum:
              - file
              - folder
    ClientError:
      title: Client error
      type: object
      x-box-resource-id: client_error
      description: A generic error
      properties:
        type:
          description: error
          example: error
          type: string
          enum:
          - error
          nullable: false
        status:
          description: The HTTP status of the response.
          example: 400
          type: integer
          format: int32
          nullable: false
        code:
          description: A Box-specific error code
          example: item_name_invalid
          type: string
          enum:
          - created
          - accepted
          - no_content
          - redirect
          - not_modified
          - bad_request
          - unauthorized
          - forbidden
          - not_found
          - method_not_allowed
          - conflict
          - precondition_failed
          - too_many_requests
          - internal_server_error
          - unavailable
          - item_name_invalid
          - insufficient_scope
        message:
          description: A short message describing the error.
          example: Method Not Allowed
          type: string
          nullable: false
        context_info:
          description: 'A free-form object that contains additional context

            about the error. The possible fields are defined on

            a per-endpoint basis. `message` is only one example.'
          type: object
          nullable: true
          properties:
            message:
              type: string
              description: More details on the error.
              example: Something went wrong.
        help_url:
          description: A URL that links to more information about why this error occurred.
          example: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/
          type: string
          nullable: false
        request_id:
          description: 'A unique identifier for this response, which can be used

            when contacting Box support.'
          type: string
          example: abcdef123456
          nullable: false