More Box Webhooks API insights

After our first blog post to start with Box webhooks, we have looked more into the webhooks api of Box the last days and we have seen some surprises. The following blog post should show you some edge cases of Box webhooks and what you should take care of.

Case 1: User deletes a folder or document in Box

A user can delete folder and documents in Box via Box standard client.

Depending on the enterprise settings for Trash, the folder and documents will be moved to the trashed first and can be deleted permanently afterwards by the user or admins only.

In the case “Trash enabled”, Box will us send a webhook message with following content :

{
  "type": "webhook_event",
  "id": "7993129a-f030-4e7c-bc1a-eed713062060",
  "created_at": "2018-11-07T15:00:21-08:00",
  "trigger": "FOLDER.TRASHED",
  "webhook": {
    "id": "104073059",
    "type": "webhook"
  },
  "created_by": {
    "type": "user",
    "id": "3926986238",
    "name": "User XY",
    "login": "userXY@fme-ag.de"
  },
  "source": {
    "id": "57718688562",
    "type": "folder"
  },
  "additional_info": []
}

You will notice the trigger FOLDER.TASHED and the folder id with value 57718688562. This makes totally sense.

I have described in another post how to get more information about the trashed file.

Case 2: User permanently deletes a folder from trash

When the user deletes the folder from the trash, it will be permanently deleted and cannot be restored anymore!

You have the choice in box to change that setting, so that only admins /coadmins can permanently delete the files.

Setting who can delete the trash content

From a webhook perspective we expect a FOLDER.DELETED event only:

{
  "type": "webhook_event",
  "id": "2a9c791a-2c72–4112–8d7d-bc7d41f31a25",
  "created_at": "2018–11–07T16:52:27–08:00",
  "trigger": "FOLDER.DELETED",
  "webhook": {
    "id": "104073059",
    "type": "webhook"
  },
  "created_by": {
    "type": "user",
    "id": "3926986238",
    "name": "User XY",
    "login": "userxy@fme-ag.de"
  },
  "source": {
    "id": "57720102629",
    "type": "folder"
  },
  "additional_info": []
}

The webhook message will arive after the delete happens in Box, so in this case you have no more information about the folder- only the previous box id.

The box cli tells us that the folder does not exist anymore:

box folders get 57720102629
-> The API returned an error [NotFound | bw5py3fx0dmdjf3f] not_found — Not Found

Case 3: User restores a folder inside of Box

If a user has deleted folder and documents, box allows to restore a folder with all previous content depending on the settings for the trash. Box will restore it on the previous location. If the previous location is not available anymore, a picker will popup to select a folder where it should be restored.

It is very interesting to see that Box triggers not only one webhook event. Instead we get a lot of events as seperate webhook messages:

• One FOLDER.RESTORED event:

{
  "type": "webhook_event",
  "id": "d308e049-349e-4082-ab26-98a175224ede",
  "created_at": "2018-11-07T17:44:23-08:00",
  "trigger": "FOLDER.RESTORED",
  "webhook": {
    "id": "104073059",
    "type": "webhook"
  },
  ...
  "source": {
    "id": "57718688562",
    "type": "folder",
  }
}

• Six FILE.RESTORED events — I have included one sample event here:

{
  "type": "webhook_event",
  "id": "77b5aef0-15c3-442d-b5e1-330c0fc26289",
  "created_at": "2018-11-07T17:44:22-08:00",
  "trigger": "FILE.RESTORED",
  "webhook": {
    "id": "104073059",
    "type": "webhook"
  },
  ...
  "source": {
    "id": "346018791046",
    "type": "file"
  },
  "additional_info": []
}

The order of the webhook messages is not deterministic. This can be a challenge if you want to process the events in order!

Case 4: Delete a folder when trash is disabled

The other case is that the trash is not activated — the folder and documents will be deleted permanently without the trash. This is not the recommended setting, but it is possible.

Disabled trash in the box admin console

The user will see a Delete button now (instead of Trash).

User sees the Delete button in the UI

And we have deleted a folder — due to the documentation we expected an event FOLDER.DELETED, but we got FOLDER.TRASHED as trigger in the webhook message:

{
  "type": "webhook_event",
  "id": "8c1d6c61-7dac-4154-908e-72273bc8e731",
  "created_at": "2018-11-07T17:05:36-08:00",
  "trigger": "FOLDER.TRASHED",
  "webhook": {
    "id": "104073059",
    "type": "webhook"
  },
  "created_by": {
    "type": "user",
    "id": "3926986238",
    "name": "UserXY",
    "login": "userXY@fme-ag.de"
  },
  "source": {
    "id": "57731448209",
    "type": "folder"
  },
  "additional_info": []
}

This is very surprising — we consider this as a bug. The webhook message was triggered for webhook with id 104073059. With Box CLI we can see the webhook details:

box webhooks get 104073059

We have configured the event triggers FILE.TRASHED and FILE.DELETED.

{
  "target": {
    "id": "57677420377",
    "type": "folder"
  },
  "created_by": {
    "name": "<name>-2018",
    "login": "<username>@boxdevedition.com",
    "is_exempt_from_device_limits": false,
    "is_exempt_from_login_verification": false,
    "id": "6351599504",
    "type": "user"
  },
  "created_at": "2018-11-07T16:15:41+01:00",
  "address": "https://<host>",
  "triggers": [
    "FILE.TRASHED",
    "FILE.DELETED",
    "FILE.RESTORED",
    "FILE.UPLOADED",
    "FILE.MOVED",
    "FILE.COPIED",
    "FILE.RENAMED",
    "FOLDER.CREATED",
    "FOLDER.TRASHED",
    "FOLDER.DELETED",
    "FOLDER.MOVED",
    "FOLDER.COPIED",
    "FOLDER.RENAMED",
    "METADATA_INSTANCE.CREATED",
    "METADATA_INSTANCE.UPDATED",
    "METADATA_INSTANCE.DELETED"
  ],
  "id": "104073059",
  "type": "webhook"
}

As you can see the webhook API can be a challenge. You have to test all different cases and behaviours to find this out because this is missing in the Box documentation. It would be a good contribution to it.