Inquiry about Retrieving File Version History with Webhooks

Hi @n.maeda san, welcome to the forum!

I’m having a little difficulty understanding your use case, so perhaps you can elaborate on it.

The only event trigger (that I can think of) that gets executed on a new version, or version revert would be the FILE.UPLOAD. You can take a look at all event triggers here.

So I’m wondering if your are monitoring the enterprise event stream.

Either way, once you get the file_id either from the stream or the webhook, you may need to execute a separate request to the Box API to get the file version history.

Let us know if this helps, and if I understood your question correctly.

Best regards

Thank you for your response.

I’m developing an application that syncs with Box to store file update history and such. All the update history is retrieved via webhooks. I’d prefer not to execute additional API requests or utilize the Enterprise stream if possible.

What I’m wondering is whether it’s possible to capture events from webhooks when, for example, a file version is reverted from v2 to v1.

Hi @n.maeda

Are you looking into the enterprise event stream?

Best regards

No, I would like to retrieve it via webhook.

Are you saying there is no way to retrieve it via webhook?

Hu @n.maeda ,

The webhook send information about the file it self, not the versions.

Here is the webhook payload, after uploading 3 versions:

{

  "type": "webhook_event",

  "id": "52190e38-8886-46fd-afe1-fe9a9c1ff86d",

  "created_at": "2024-04-09T08:07:34-07:00",

  "trigger": "FILE.UPLOADED",

  "webhook": {

    "id": "2546627740",

    "type": "webhook"

  },

  "created_by": {

    "type": "user",

    "id": "18622116055",

    "name": "Rui Barbosa",

    "login": "barduinor@gmail.com"

  },

  "source": {

    "id": "1496636677591",

    "type": "file",

    "file_version": {

      "type": "file_version",

      "id": "1643064801486",

      "sha1": "9650d7a6213181771fd38e761e2c2a330848a5fc"

    },

    "sequence_id": "2",

    "etag": "2",

    "sha1": "9650d7a6213181771fd38e761e2c2a330848a5fc",

    "name": "Document (PDF).pdf",

    "description": "",

    "size": 792687,

    "path_collection": {

      "total_count": 2,

      "entries": [

        {

          "type": "folder",

          "id": "0",

          "sequence_id": "None",

          "etag": "None",

          "name": "All Files"

        },

        {

          "type": "folder",

          "id": "253757099719",

          "sequence_id": "0",

          "etag": "0",

          "name": "CCS 24"

        }

      ]

    },

    "created_at": "2024-04-09T07:56:11-07:00",

    "modified_at": "2024-04-09T08:07:34-07:00",

    "trashed_at": "None",

    "purged_at": "None",

    "content_created_at": "2024-04-08T06:44:29-07:00",

    "content_modified_at": "2024-04-08T06:44:29-07:00",

    "created_by": {

      "type": "user",

      "id": "18622116055",

      "name": "Rui Barbosa",

      "login": "barduinor@gmail.com"

    },

    "modified_by": {

      "type": "user",

      "id": "18622116055",

      "name": "Rui Barbosa",

      "login": "barduinor@gmail.com"

    },

    "owned_by": {

      "type": "user",

      "id": "18622116055",

      "name": "Rui Barbosa",

      "login": "barduinor@gmail.com"

    },

    "shared_link": "None",

    "parent": {

      "type": "folder",

      "id": "253757099719",

      "sequence_id": "0",

      "etag": "0",

      "name": "CCS 24"

    },

    "item_status": "active"

  },

  "additional_info": []

}

As you can see there is no information on the versions, this is because versioning is handled by another endpoint. To get the versions of the file you would need to query the API, here is an example:

curl --location 'https://api.box.com/2.0/files/1496636677591/versions' \

--header 'Authorization: Bearer kU...63' 

Resulting in:

{

    "total_count": 2,

    "entries": [

        {

            "type": "file_version",

            "id": "1643057382586",

            "sha1": "9650d7a6213181771fd38e761e2c2a330848a5fc",

            "name": "Document (PDF).pdf",

            "size": 792687,

            "created_at": "2024-04-09T08:01:30-07:00",

            "modified_at": "2024-04-09T08:01:30-07:00",

            "modified_by": {

                "type": "user",

                "id": "18622116055",

                "name": "Rui Barbosa",

                "login": "barduinor@gmail.com"

            },

            "trashed_at": null,

            "purged_at": null

        },

        {

            "type": "file_version",

            "id": "1643046018391",

            "sha1": "9650d7a6213181771fd38e761e2c2a330848a5fc",

            "name": "Document (PDF).pdf",

            "size": 792687,

            "created_at": "2024-04-09T07:56:11-07:00",

            "modified_at": "2024-04-09T07:56:11-07:00",

            "modified_by": {

                "type": "user",

                "id": "18622116055",

                "name": "Rui Barbosa",

                "login": "barduinor@gmail.com"

            },

            "trashed_at": null,

            "purged_at": null

        }

    ],

    "limit": 1000,

    "offset": 0

}

If you have an application that syncs with Box and receives the webhook, it should’t be too difficult to get the versions history when it receives the webhook payload.

We have plenty of SDK options for you.

Another option that I’ve seen being implemented by partners is to monitor the the enterprise event stream.

Here are a couple of articles about this topic

I’m not sure if you are Japanese, but if so, a Japanese version of those articles does exist in our Japanese Medium Blogs:

Best regards

Thank you for your support.

What I’m interested in is not the information when a file is uploaded and updated, but rather when the file version is reverted. For example, when the file version is reverted from v2 to v1.

If it’s not possible to retrieve this information via webhook, is there any efficient way to obtain it?

I find it difficult to use the Enterprise event stream due to issues such as permissions.

I don’t think polling for each file to retrieve information would be efficient.

Hi @n.maeda ,

As I mentioned in my previous messages:

• The webhook payload will only give information about the file.


• To get information about the versions you will need to query another endpoint in the Box API.


• You might be able to get this information in using the event stream.

I understand this is not ideal for your use case, however it does present a path forward.

I’ve shared with you how other partners with similar use case (like monitoring what happens to documents, for example in DocuTracker) moved forward.

As I see it, 2 options are presented:

• Find a way to work within the current constraints of the Box Platform.


• Suggest a product improvement using Box Pulse.

We are here to help you on your path, let us know how we can help you move forward.

Best regards

Thank you for your support.

I understand that the information cannot be obtained via webhook. I’m the developer of DocuTracker. Thank you for mentioning it as an example.

On a different note, I believe that the functionality to revert file versions is only available in paid plans. Is there a way to verify if a user has the permission to revert file versions using a paid plan?

For example, would it be possible to determine the status of whether a user has access to features like reverting file versions if we have the enterprise key? What I want to do is narrow down the target users to some extent in order to track the reverting of file versions.

Hi @n.maeda,

I was asking internally about this, and versioning is either turned on or off, depending on the Box tier and administrator configurations. The free tiers of Box do not have versions at all.

If the Box tier does have versions then it is available for all users.

For more detail, please take a look at this support note.

Hope this helps

Best regards

Thank you for your response.

Is it possible to check if a Box tier has versions functionality using the API?

Hi @n.maeda ,

Took me a while to look this up, and I couldn’t find a way.

The way this is set up is to not return an error. What I mean by this is that it will always allow a user to upload a new file version, but for lower tier account it wont keep the file version history.

Hope this helps.

Thank you for your support.

That’s all the questions I have, so please feel free to close this thread as needed.