Box Webhook Deep Dive on the example of a trashed file event

If a user deletes a document in box, it will be moved to the box trash. The user can restore the document later or permanently delete the file which will cause different webhook events.

Delete the document tothe trash

Box User Interface for Trash

The box platform will send a webhook message with the event trigger FILE.TRASHED if somebody registered a webhook for this event on one of the parent folder or the file itself.

Box will send following JSON message to your registered service:

{
    "type": "webhook_event",
    "id": "f0734b45-c30a-4de9-bbd3-671a57e1a3d3",
    "created_at": "2018-11-06T07:48:36-08:00",
    "trigger": "FILE.TRASHED",
    "webhook": {
        "id": "102720447",
        "type": "webhook"
    },
    "created_by": {
        "type": "user",
        "id": "6359720339",
        "name": "User XY",
        "login": "userxy@fme.de"
    },
    "source": {
        "id": "345058226587",
        "type": "file"
    },
    "additional_info": []
}

This behaviour makes absolutely sense, but wait a second- we only get the id of the document in the source block?! What about other metadata like the previous parent folder or the name of the document?

Box provides a REST API for the trash. Important to know is that the trash endpoint is user specific - this means that each user has its own trash.

curl -X GET https://api.box.com/2.0/folders/trash/items

You get the following response:

{
    "total_count": 1,
    "entries": [
            "type": "file",
            "id": "345058226587",
            "file_version": {
                "type": "file_version",
                "id": "364458478987",
                "sha1": "c1070232e8a0ec6ee0575acbf54bd5f0c6365b00"
            },
            "sequence_id": "1",
            "etag": "1",
            "sha1": "c1070232e8a0ec6ee0575acbf54bd5f0c6365b00",
            "name": "Photo_racing (1).jpg"
        }
      ],
      "offset": 0,
      "limit": 100,
      "order": [
        {
            "by": "type",
            "direction": "ASC"
        },
        {
            "by": "name",
            "direction": "ASC"
        }
    ]
}

Ok, the items in the trash we got back from Box contain the name of the document, but we do not know where the document was located before. In our use case we needed the information.
Looking deeper into the rest API documentation of Box, we see an additional api endpoint to get more information about the trashed file. You have to use the following endpoint:

 GET https://api.box.com/2.0/files/345058226587/trash

You get following response:

{
  "type": "file",
  "id": "345058226587",
  "file_version": {
    "type": "file_version",
    "id": "364458478987",
    "sha1": "c1070232e8a0ec6ee0575acbf54bd5f0c6365b00"
  },
  "sequence_id": "1",
  "etag": "1",
  "sha1": "c1070232e8a0ec6ee0575acbf54bd5f0c6365b00",
  "name": "Photo_racing (1).jpg",
  "description": "",
  "size": 915469,
  "path_collection": {
    "total_count": 1,
    "entries": [
      {
        "type": "folder",
        "id": "1",
        "sequence_id": null,
        "etag": null,
        "name": "Trash"
      }
    ]
  },
  "created_at": "2018-11-06T07:42:50-08:00",
  "modified_at": "2018-11-06T07:42:50-08:00",
  "trashed_at": "2018-11-06T07:48:35-08:00",
  "purged_at": "2018-12-06T07:48:35-08:00",
  "content_created_at": "2018-11-06T07:41:53-08:00",
  "content_modified_at": "2018-11-06T07:41:53-08:00",
  "created_by": {
    "type": "user",
    "id": "6359720339",
    "name": "UserXYZ"
    "login": "userxyz@fme.de"
  },
  "modified_by": {
    "type": "user",
    "id": "6359720339",
    "name": "User XY",
    "login": "userxy@fme.de"
  },
  "owned_by": {
    "type": "user",
    "id": "3926986238",
    "name": "User XYZ",
    "login": "userxyz@fme.de"
  },
  "shared_link": null,
  "parent": {
    "type": "folder",
    "id": "57483101689",
    "sequence_id": "0",
    "etag": "0",
    "name": "Test"
  },
  "item_status": "trashed"
}

There is a lot of interesting metadata in the JSON response.

• You see the item_status which is not active like for other documents not in the trash, but trashed.
• The parent block contains the folder where the document was previously located.
• The path_collection instead contains the new path — the trash itself
• trashed_at is the date when the document was deleted by the user (and moved to the trash)
• purged_at is the future date (1 month after trashed_at) when the document will be deleted.

When you process a webhook for a trashed file, it is sometimes necessary to get more information about the trashed file.
The webhook message does not contain the information, so we can use the Box REST API to get more information about a trashed file.