Skip to content

Latest commit

 

History

History
156 lines (120 loc) · 5.56 KB

webhooks.md

File metadata and controls

156 lines (120 loc) · 5.56 KB
Raw

Webhooks

Webhooks enable you to attach event triggers to Box files and folders. Event triggers monitor events on Box objects and notify your application when they occur. A webhook notifies your application by sending HTTP requests to a URL of your choosing.

Get a Webhook

A webhook infocan be retrieved by calling the getInfo(String... fields) method.

BoxWebHook webhook = new BoxWebHook(api, id);
BoxWebHook.Info info = webhook.getInfo();

Get All Webhooks

Calling the static all(BoxAPIConnection api, String... fields) will return an iterable that will page through all defined webhooks for the requesting application and user.

Iterable<BoxWebHook.Info> webhooks = BoxWebHook.all(api);
for (BoxWebHook.Info webhookInfo: webhooks) {
    // Do something with the webhook.
}

Create a Webhook

The static create(BoxResource targetItem, URL callbackURL, BoxWebHook.Trigger... triggerEvents) method will let you create a new webhook for a specified target object.

// Listen for preview events for a file
BoxFile file = new BoxFile(api, id);
BoxWebHook.Info webhookInfo = BoxWebHook.create(file, url, BoxWebHook.Trigger.FILE.PREVIEWED);
// Listen for file upload events in the specified folder
BoxFolder folder = new BoxFolder(api, id);
BoxWebHook.Info webhookInfo = BoxWebHook.create(folder, url, BoxWebHook.Trigger.FILE_UPLOADED);

Delete a Webhook

A webhook can be deleted by calling the delete() method.

BoxWebHook webhook = new BoxWebHook(api, id);
webhook.delete();

Update a Webhook

A webhook can be updated by calling the update(BoxWebHook.Info fieldsToUpdate) method.

BoxWebHook webhook = new BoxWebHook(api, id);
BoxWebHook.Info info = webhook.getInfo();
info.addPendingChange("address", url);
webhook.update(info);

Verify a Webhook Message

When you receive a webhook message from Box, you should validate that it actually came from Box by calling BoxWebHookSignatureVerifier#verify(String sigVersion, String sigAlgorithm, String primarySignature, String secondarySignature, String payload, String deliveryTimestamp)

Note: It is recommended to ensure that your application and verifier use both a primary and secondary key to ensure that these keys can be safely rotated.

// Webhook message contents are shown for demonstration purposes
// Normally these would come from your HTTP handler

// Webhook message HTTP body
String messagePayload = "{"
    + "\"type\":\"webhook_event","
    + "\"webhook\":{"
    +   "\"id\":\"1234567890\""
    + "},"
    + "\"trigger\":\"FILE.UPLOADED\","
    + "\"source\":{"
    +   "\"id\":\"1234567890\","
    +   "\"type\":\"file\","
    +   "\"name\":\"Test.txt\""
    + "}}";

// Webhook message HTTP headers
Map<String, String> messageHeaders = new HashMap<String, String>();
headers.put("BOX-DELIVERY-ID", "f96bb54b-ee16-4fc5-aa65-8c2d9e5b546f");
headers.put("BOX-DELIVERY-TIMESTAMP", "2020-01-01T00:00:00-07:00");
headers.put("BOX-SIGNATURE-ALGORITHM", "HmacSHA256");
headers.put("BOX-SIGNATURE-PRIMARY", "6TfeAW3A1PASkgboxxA5yqHNKOwFyMWuEXny/FPD5hI=");
headers.put("BOX-SIGNATURE-SECONDARY", "v+1CD1Jdo3muIcbpv5lxxgPglOqMfsNHPV899xWYydo=");
headers.put("BOX-SIGNATURE-VERSION", "1");

// Your application's webhook keys, obtained from the Box Developer Console
String primaryKey = "4py2I9eSFb0ezXH5iPeQRcFK1LRLCdip";
String secondaryKey = "Aq5EEEjAu4ssbz8n9UMu7EerI0LKj2TL";

BoxWebHookSignatureVerifier verifier = new BoxWebHookSignatureVerifier(primaryKey, secondaryKey);
boolean isValidMessage = verifier.verify(
    headers.get("BOX-SIGNATURE-VERSION"),
    headers.get("BOX-SIGNATURE-ALGORITHM"),
    headers.get("BOX-SIGNATURE-PRIMARY"),
    headers.get("BOX-SIGNATURE-SECONDARY"),
    messagePayload,
    headers.get("BOX-DELIVERY-TIMESTAMP")
);

if (isValidMessage) {
    // Message is valid, handle it
} else {
    // Message is invalid, reject it
}