Salesforce/Box V1 Webhooks

Box is a cloud-based file management service that offers collaboration for businesses and individuals. This recipe shows how to send real-time Box folder notifications into Salesforce using Streamscript and Box V1 Webhooks. (Looking for Box V2 Webhooks? V2 recipe »)

img

 

This integration uses three steps:

 

Follow this recipe by creating a 'Proposals' folder in the Box app, then open the Dev Console to access apps and webhooks. Webhooks are included in all Box Enterprise plans.

img

 

Step 1 - Create a webhook receiver in Salesforce

Log into Salesforce and prepare a Flow to handle the webhooks.

# Streamscript to read the Box callback parameters
$file = $Webhook.requestParams.item_name
$type = $Webhook.requestParams.event_type
$name = $Webhook.requestParams.from_user_name 

# Secure the endpoint with a token of your choosing
if ($Webhook.requestParams.token != 'ABC123') {throw 'Bad Token'}

# Prepare Task
$Task = New-Task
$Task.Subject = `Box activity: $type`
$Task.Description = `User $name interacted with: $file` 
return $Task

 

Add a flow element to save the Task.

img

 

Save the Flow:

img

 

Notice how the API Name of the Webhook Flow consists of three parts. This is a
convention and it always has the format: Webhook _ Site Name _ URL Suffix

img

 

Step 2 - Configure Box to send file events with V1 Webhooks

Log into Box > Dev Console > My Apps:

img

 

Carefully choose the app settings:

img img

 

Now configure the Box webhook.

img

 

General Information

img

 

Endpoint Configuration

img

 

Callback Parameters are keys and values contained in the webhook payload. Include all of them so that Salesforce receives the full event detail. For each row, click Add callback parameter:

img

Add one last parameter - a hard coded value containing a secure token of your own choosing. This is used by the webhook endpoint to verify each request came from you.

 

Finally, install your app in your Box account using the preview process.
This option keeps the app private and does not require approval from Box.

img

It navigates you directly to the app awaiting install in your Box environment. Click Add.

img img

 

Step 3 - Test the integration with a file upload

Log into your Box workspace. From the blue navigation menu, click Files then the Proposals folder. Drag and drop a test file into the folder to upload it.

img

img

 

Log into Salesforce. Go to the Tasks tab and open the list view. Here is the upload notification!

img

 

This simple Box/Salesforce integration needs no OAuth implementation nor token refresh logic. All file and folder events are sent from Box into Salesforce via the webhook.

 

Appendix - Example Data

HTTP Headers for Box V1 Webhooks

Callback Parameters for Box V1 Webhooks

$Webhook request and response properties

$Webhook.request # null
$Webhook.requestMethod # GET
$Webhook.requestIp # 74.112.186.52
$Webhook.requestUri # /Streams/BoxV1
$Webhook.requestPath # /services/apexrest/Streams/*
$Webhook.requestParams # {item_name: "Screenshot.png"...}
$Webhook.requestHeaders {X-Salesforce-SIP: "74.112.186.52"...}
$Webhook.responseStatus # 200
$Webhook.responseHeaders # {...}
$Webhook.response # blank
 

 

Getting started with Streamscript
Install from the Salesforce AppExchange
Package install link: /packaging/installPackage.apexp?p0=04tGA000005dF3W