Box Events

Axway AMPLIFY supports events via polling or webhooks, depending on the API provider. For more information about our Events framework, see Events Overview.

Supported Events and Resources

Axway AMPLIFY supports webhook events for Box. For more information about webhooks at Box, including the currently available webhooks, see their webhooks documentation.

Webhooks

Box provides two versions for webhooks - Webhooks v1 and Webhooks v2. Depending on your needs, you can opt for v1 or v2. Webhooks v1 offers limited events on all objects in your profile. Webhooks v2 offers all events on specific objects (files or folders) in your profile. To enable Webhooks v1, you must set up webhooks in Box first and then provision an instance with the Box connector. Webhooks v2, on the other hand, offers APIs which are enabled as normal APIs in the Axway AMPLIFY platform.

Webhooks v1

To enable webhooks v1, follow the steps below to set up your Box application. 

  1. On the Box website, click on the My Apps button on the top.
  2. Log in using your credentials for Box. If you don't already have an account with them, create an account. 
  3. Once you're logged in, you need to create an app. If you already have an app, jump to step 8.
  4. To create a new app, click on the Create new app button.
  5. Choose what type of app you wish to build and click Next. In the example below, we are building a Custom app.
  6. Next, select the Standard OAuth 2.0 (User Authentication) type for your app and click Next.
  7. Give your app a name and click on the Create app button.
  8. If you have an app that already exists, click on the app and then on the navigation panel to your left.
  9. Click Webhooks.
  10. In the Webhooks V1 section, click Create a new webhook.
  11. Configure it based on your requirements and click Save Webhook.
  12. If the application is for a production account, as opposed to a sandbox account, then you will need to get in contact with Box's support to enable webhooks for that application.

After you set up webhooks on the Box website, provision an instance with the Box connector with events enabled to get webhooks working.

Webhooks v2

Box Webhooks v2 enables webhooks by offering APIs. These APIs are offered as normal APIs by Axway AMPLIFY. 

Here is what you need to do to enable webhooks v2. 

  1.  Provision an instance with the Box connector with Events enabled. 
  2. Call our normalized API POST/webhooks and mention the target that is, the folder/file you want events to be enabled for and the triggers.

You have now enabled webhooks v2. 

Icon
There are a few limitations affecting webhooks v2 in Box, which apply to the above steps. You can find them here.

Configure Webhooks Through API

Use the /instances endpoint to authenticate with Box and create a connector instance with webhooks enabled.

Icon

The endpoint returns a connector instance token and ID upon successful completion. Retain the token and ID for all subsequent requests involving this connector instance.

To authenticate a connector instance with webhooks:

  1. Get an authorization grant code by completing the steps in authenticating and authenticate.
  2. Construct a JSON body, as shown below (see Parameters):

    {
      "element": {
        "key": "box"
      },
      "providerData": {
        "code": "<AUTHORIZATION_GRANT_CODE>"
      },
      "configuration": {
        "oauth.callback.url": "<CALLBACK_URL>",
        "oauth.api.key": "<CONSUMER_KEY>",
        "oauth.api.secret": "<CONSUMER_SECRET>",
        "event.notification.enabled": true,
        "event.notification.callback.url": "<CALLBACK_URL>",
        "events.list.ids": "<LIST_IDS>"
      },
      "tags": [
        "<Add_Your_Tag>"
      ],
      "name": "<INSTANCE_NAME>"
    }
  3. Call the following, including the JSON body you constructed in the previous step:

    POST /instances
    Icon

    Make sure that you include the User and Organization keys in the header. For more information, see Authorization Headers, Organization Secret, and User Secret.

  4. Locate the token and id in the response and save them for all future requests using the connector instance.

Example cURL

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2//instances \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '{
  "element": {
    "key": "box"
  },
  "providerData": {
    "code": "xoz8AFqScK2ngM04kSSM"
  },
  "configuration": {
    "oauth.callback.url": "https://mycoolapp.com",
    "oauth.api.key": "xxxxxxxxxxxxxxxxxx",
    "oauth.api.secret": "xxxxxxxxxxxxxxxxxxxxxx"
    "event.notification.enabled": true,
    "event.notification.callback.url": "https://mycoolapp.com/events",
    "event.notification.signature.key": "xxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  "tags": [
    "Docs"
  ],
  "name": "API Instance"
}'

Parameters

API parameters not shown in the Axway AMPLIFY are in code formatting.

Parameter Description Data Type
key The connector key. string
code The authorization grant code returned from the API provider in an OAuth2 authentication workflow. string
Name
name
The name for the connector instance created during authentication. Body
oauth.callback.url The URL where you want to redirect users after they grant access. This is the Callback URL that you noted in the API Provider Setup section.  
oauth.api.key The Client ID from Box. This is the Client ID that you noted in the API Provider Setup section. string
oauth.api.secret The Client Secret from Box. This is the Client Secret that you noted in the API Provider Setup section. string
Events Enabled
event.notification.enabled
Optional. Identifies that events are enabled for the connector instance.
Default: false
boolean
Event Notification Callback URL
event.notification.callback.url
The URL where you want Axway AMPLIFY to send the events. string
Callback Notification Signature Key
event.notification.signature.key
Optional. A user-defined key for added security to show that events have not been tampered with. string
tags Optional. User-defined tags to further identify the instance. string

Related Links