Book a demo

Event

trigger.box_event
TriggerFiles & storageconnection requiredruns in-engine

Registers a Box V2 webhook on the watched item at publish time and starts one run per delivery, verified against Box's signature keys.

Start a run when a Box file or folder is uploaded to, changed or shared.

Ask about BoxAll Box nodesProvider API docs ↗

Connection

Required
Yes — the node will not save without one
Auth type
OAuth 2.0
Providers
Box
Secret shape
the Box app credential, plus webhook_signature_primary_key (and webhook_signature_secondary_key while a key is being rotated)
Resolved by
config.connection_id, else node.connection_id
Note
Box generates the two webhook signature keys in the Developer Console (the app's Webhooks tab, Manage signature keys) and no API returns them, so the primary key must be stored on this connection as webhook_signature_primary_key. Publishing without it is refused: Box would sign deliveries that could never be verified. Publishing also needs MANTLE_APP_PUBLIC_BASE_URL set to an https URL on port 443 with a CA-signed certificate — Box refuses anything else.

Configuration

3 fields, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

FieldTypeRequiredDefaultConstraintsExample
target_type
Whether the watched item is a folder (events for everything inside it) or a single file.
stringNofolderone of "file", "folder"—
target_id
Id of the file or folder to watch, from its Box URL. Read when the workflow is published, so it must be a literal id rather than a {{ }} expression. The root folder (id 0) cannot be watched.
stringYes—matches ^[0-9]+$123456789012
triggers
Box trigger names to subscribe to. One Box webhook covers all of them, and each delivery starts one run.
arrayNo["FILE.UPLOADED"]1–43 characters; array of string—

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "target_id": "123456789012",
  "target_type": "folder",
  "triggers": [
    "FILE.UPLOADED"
  ]
}

Output

One shape.

box event

The flattened Box webhook invocation. payload's keys vary by trigger, so the shape is open below the declared fields.

Extra keys beyond the ones listed can appear.

FieldTypeExample
id
Box's own id for this event, and the run's idempotency key. It stays the same across every retry of the same event, unlike the BOX-DELIVERY-ID header, which changes each time.
stringeb0c4e06-751f-442c-86f8-fd5bb404dbec
trigger
The trigger that fired, e.g. FILE.UPLOADED. Branch on this when the webhook subscribes to more than one.
stringFILE.UPLOADED
created_at
When Box raised the event, as an RFC-3339 timestamp with the account's UTC offset.
string2016-07-11T10:10:32-07:00
delivery_id
BOX-DELIVERY-ID: which attempt this was. Useful in logs; never as an idempotency key, because a retry carries a new one.
string—
webhook_id
The Box webhook that fired.
string53
source.id
Id of the file or folder the event is about — the file that was uploaded, not the folder being watched.
string73835521473
source.type
Whether that item is a 'file' or a 'folder'.
stringfile
source.name
Its name.
stringTest-Image-3.png
source.parent_id
Id of the folder the item sits in, or '' when Box sent no parent.
string8290188973
created_by.id
Id of the Box user whose action fired the trigger.
string—
created_by.login
That user's login (their email address).
string—
created_by.name
That user's display name.
string—
additional_info
Extra context Box attaches to some events — most usefully {'reason': 'auto_cleanup'} on WEBHOOK.DELETED, which says the subscription was retired at Box's end. Empty on most events.
object—
payload
Box's webhook body exactly as sent, for everything the fields above do not lift out (file_version, path_collection, the metadata instance, shared-link details).
object—
{
  "additional_info": {},
  "created_at": "2016-07-11T10:10:32-07:00",
  "created_by": {
    "id": "226067247",
    "login": "johnq@dev.name",
    "name": "John Q. Developer"
  },
  "delivery_id": "673a081b-bb4b-4d45-b4f1-4131a29c1d07",
  "id": "eb0c4e06-751f-442c-86f8-fd5bb404dbec",
  "payload": {
    "id": "eb0c4e06-751f-442c-86f8-fd5bb404dbec",
    "type": "webhook_event"
  },
  "source": {
    "id": "73835521473",
    "name": "Test-Image-3.png",
    "parent_id": "8290188973",
    "type": "file"
  },
  "trigger": "FILE.UPLOADED",
  "webhook_id": "53"
}

Notes

  • Publishing creates the webhook in Box; unpublishing, disabling or archiving deletes it. A workflow that is off is off at Box too.
  • Box allows one webhook per item, per application, per user — a second workflow watching the same folder through the same Box app is refused by Box, even for different triggers.
  • The root folder (id 0) cannot be watched; watch the subfolders instead.
  • Box deletes a webhook that has had no successful delivery for 30 days, and sends a final WEBHOOK.DELETED event with additional_info.reason when it does.
  • Deliveries older than ten minutes are refused, which is Box's own replay window.

Related Box nodes

See Event run in a workflow.

In a technical demo we add the Box connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demoTalk to sales