Skip to main content
POST
/
webhooks
cURL
curl -i -X POST "https://api.box.com/2.0/webhooks" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "target": {
         "id": "21322",
         "type": "file"
       },
       "address": "https://example.com/webhooks",
       "triggers": [
         "FILE.PREVIEWED"
       ]
     }'
{
  "id": "11446498",
  "type": "webhook",
  "target": {
    "id": "1231232",
    "type": "file"
  },
  "created_by": {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "[email protected]"
  },
  "created_at": "2012-12-12T10:53:43-08:00",
  "address": "https://example.com/webhooks",
  "triggers": [
    "FILE.UPLOADED"
  ]
}
This endpoint is in the version 2024.0. No changes are required to continue using it. For more details, see Box API versioning.Learn more about Box SDK versioning strategy.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json
​
target
object
required

The item that will trigger the webhook.

​
address
string
required

The URL that is notified by this webhook.

Example:

"https://example.com/webhooks"

​
triggers
enum<string>[]
required

An array of event names that this webhook is to be triggered for.

The event name that triggered this webhook.

Available options:
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,
SIGN_REQUEST.SIGN_SIGNER_SIGNED,
SIGN_REQUEST.SIGN_DOCUMENT_CREATED,
SIGN_REQUEST.SIGN_ERROR_FINALIZING
Example:
["FILE.UPLOADED"]

Response

Returns the new webhook object.

Represents a configured webhook.

​
id
string

The unique identifier for this webhook.

Example:

"11446498"

​
type
enum<string>

The value will always be webhook.

Available options:
webhook
Example:

"webhook"

​
target
object

The item that will trigger the webhook.

​
created_by
User (Mini) · object

The user who created the webhook.

​
created_at
string<date-time>

A timestamp identifying the time that the webhook was created.

Example:

"2012-12-12T10:53:43-08:00"

​
address
string

The URL that is notified by this webhook.

Example:

"https://example.com/webhooks"

​
triggers
enum<string>[]

An array of event names that this webhook is to be triggered for.

The event name that triggered this webhook.

Available options:
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,
SIGN_REQUEST.SIGN_SIGNER_SIGNED,
SIGN_REQUEST.SIGN_DOCUMENT_CREATED,
SIGN_REQUEST.SIGN_ERROR_FINALIZING
Example:
["FILE.UPLOADED"]