Skip to content

Latest commit

 

History

History
138 lines (107 loc) · 6.16 KB

webhook.md

File metadata and controls

138 lines (107 loc) · 6.16 KB

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 Information about Webhook

To get a webhook object, first call client.webhook(webhook_id) to construct the appropriate Webhook object, and then calling webhook.get(*, fields=None, headers=None, **kwargs) will return the Webhook object populated with data from the API.

webhook = client.webhook(webhook_id='12345').get()
print(f'Webhooks ID is {webhook.id} and the address is {webhook.address}')

List all Webhooks

To retrieve all webhooks for an enterprise, call client.get_webhooks(limit=None, marker=None, fields=None). This method returns a BoxObjectCollection that allows you to iterate over the Webhook objects in the collection.

webhooks = client.get_webhooks()
for webhook in webhooks:
    print(f'The webhook ID is {webhook.id} and the address is {webhook.address}')

Create Webhook

To create a webhook object, call client.create_webhook(target_url, name=None, description=None) will let you create a new webhook object with the specified target url, name, and description. This method will return an updated Webhook object populated with data from the API, leaving the original object unmodified.

file = client.file(file_id='12345')
webhook = client.create_webhook(file, ['FILE.PREVIEWED'], 'https://example.com')
print(f'Webhook ID is {webhook.id} and the address is {webhook.address}')
folder = client.folder(folder_id='12345')
webhook = client.create_webhook(folder, ['FILE.UPLOADED', 'FILE.PREVIEWED'], 'https://example.com')
print(f'Webhook ID is {webhook.id} and the address is {webhook.address}')

Delete Webhook

To delete a webhook, call webhook.delete(). This method returns True to indicate that the deletion was successful.

client.webhook(webhook_id='12345').delete()
print('The webhook was successfully deleted!')

Update Webhook

To update a webhook object, first call client.webhook(webhook_id) to construct the appropriate Webhook object, and then calling webhook.update_info(data=update_object) with a dict of properties to update on the webhook. This method returns a new updated Webhook object, leaving the original object unmodified.

update_object = {
    'triggers': ['FILE.COPIED'],
    'address': 'https://newexample.com',
}
webhook = client.webhook(webhook_id='12345').update_info(data=update_object)
print(f'Updated the webhook info for triggers: {webhook.triggers} and address: {webhook.address}')

Validate Webhook Message

When you receive a webhook message from Box, you should validate it by calling [Webhook.validate_message(body, headers, primary_key, secondary_key)][validate_webhook]. This will protect your application against attacks. Verification ensures that the notifications were actually sent by Box and not by a malicious party and that the contents of the notification haven't been changed.

body = b'{"webhook":{"id":"1234567890"},"trigger":"FILE.UPLOADED","source":{"id":"1234567890","type":"file","name":"Test.txt"}}'
headers = {
    'box-delivery-id': 'f96bb54b-ee16-4fc5-aa65-8c2d9e5b546f',
    'box-delivery-timestamp': '2020-01-01T00:00:00-07:00',
    'box-signature-algorithm': 'HmacSHA256',
    'box-signature-primary': '4KvFa5/unRL8aaqOlnbInTwkOmieZkn1ZVzsAJuRipE=',
    'box-signature-secondary': 'yxxwBNk7tFyQSy95/VNKAf1o+j8WMPJuo/KcFc7OS0Q=',
    'box-signature-version': '1',
}
is_validated = Webhook.validate_message(body, headers, primary_key, secondary_key)
print(f'The webhook message is validated to: {is_validated}')