Box Developer Documentation
Log in

Invocation URL

Guides Box Skills Invocation URL
Edit this page

Invocation URL

When creating a new Box Skills application you will be asked to supply an invocation_url. This URL is the public web address where Box will send the event notification payload when a file is uploaded, copied, or moved within a folder monitored by the Skills app.

The website or application that is listening for those notifications functions as a bridge between the file on Box and the system that is being employed to garner insight from the file, such as the machine learning system.

Requirements

  • The invocation URL should be publicly available. Notifications cannot be sent to localhost or 127.0.0.1 as this address is not accessible by Box's servers.
  • The server behind the invocation URL should be listening to HTTP POST requests. Box Skills will send the event notification via a POST request using a JSON body.

Hosting Tips & Tricks

There are a number of ways to quickly expose a an application on a public URL so that Box's servers can use this as the invocation_url.

  • A local tunnel - One of the quickest ways to expose a web application on a developer's machine to a public address is by using a local tunnel. Popular tunneling tools include ngrok and localtunnel.
  • Serverless functions - A great way to set up a server that can handle a Box Skill is as a serverless function. Box Skills can generate a varied amount of invocations depending on the (lack of) activity in the folders being observed. Serverless functions such as AWS Lambda, Google Cloud Functions, or Microsoft Azure Functions are a natural fit for these kind of sporadic events. The serverless functions will only run and be billed when the event is being processed.
  • Traditional application hosting - Traditional application hosting solutions, such as Heroku, Firebase, AWS or GCP are other viable options if serverless technology is not preferred. These applications will be hosted on their respective services and have an publicly exposed URL for the app that will be used as the invocation URL.

Application Server details

Typically the application behind the invocation URL will need to perform the following tasks.

  1. Capture the event notification from Box.
  2. Send the binary data for the Box file (or its URL) to a processing service
  3. Listen for the response from the processing service.
  4. Format the response from the processing service into a Box metadata format.
  5. Apply the new metadata back to the file stored on Box.